devframe 0.9.2 → 0.9.3

package/dist/{devframe-mbfgpQQC.d.mts → context-_i51nYOs.d.mts}

@@ -1,50 +1,11 @@
-import { d as RpcFunctionsCollectorBase } from "./index-tdrk1bzV.mjs";
-import { _ as RpcFunctionDefinition, v as RpcFunctionDefinitionAny } from "./types-Djq7CBXh.mjs";
-import { d as DevframeRpcConnection, u as DevframeNodeRpcSessionMeta } from "./ws-server-D1d3QM9f.mjs";
-import { m as defineDiagnostics } from "./nostics-SPGDgHEP.mjs";
+import { d as RpcFunctionsCollectorBase } from "./index-DOg4S5wk.mjs";
+import { _ as RpcFunctionDefinition, v as RpcFunctionDefinitionAny } from "./types-BBLeGfpt.mjs";
+import { d as DevframeRpcConnection, u as DevframeNodeRpcSessionMeta } from "./ws-server-DLtEoLdR.mjs";
 import { a as RemoteAssetsStore, o as StaticAssetsSource } from "./remote-assets-Bg4gCUZ_.mjs";
-import { CAC } from "cac";
-import { StandardSchemaV1 } from "@standard-schema/spec";
+import { m as defineDiagnostics } from "./nostics-SPGDgHEP.mjs";
 import { BirpcReturn } from "birpc";
-//#region src/adapters/flags.d.ts
-/**
- * Schema map for typed CLI flags. Keys are flag names in camelCase —
- * 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[];
-};
-//#endregion
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import { CAC } from "cac";
 //#region src/types/events.d.ts
 interface EventsMap {
   [event: string]: any;
@@ -313,235 +274,144 @@ interface DevframeAgentHost {
   getResource: (id: string) => AgentResource | undefined;
 }
 //#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]>; };
+//#region src/adapters/flags.d.ts
 /**
- * Serializable patch describing a single mutation to a `SharedState`.
- * Structurally compatible with JSON-Patch and is safe to send over RPC.
+ * Schema map for typed CLI flags. Keys are flag names in camelCase —
+ * 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 })`.
  */
-interface SharedStatePatch {
-  op: 'add' | 'remove' | 'replace';
-  path: readonly (string | number)[];
-  value?: unknown;
-}
+type CliFlagsSchema = Record<string, StandardSchemaV1>;
 /**
- * State host that is immutable by default with explicit mutate.
+ * 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
+ *   },
+ * })
+ * ```
  */
-interface SharedState<T> {
-  /**
-   * Get the current state. Immutable.
-   */
-  value: () => Immutable<T>;
-  /**
-   * Subscribe to state changes.
-   */
-  on: EventEmitter<SharedStateEvents<T>>['on'];
+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
+/**
+ * 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 {
   /**
-   * Mutate the state.
+   * `anonymous:devframe:auth` + `anonymous:devframe:auth:exchange` (the
+   * handshake) and `devframe:auth:revoke` (self-revoke) — register these on
+   * the RPC host (e.g. `rpcHost.register(fn)` for each).
    */
-  mutate: (fn: (state: T) => void, syncId?: string) => void;
+  rpcFunctions: RpcFunctionDefinitionAny[];
   /**
-   * Apply patches to the state.
+   * 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.
    */
-  patch: (patches: SharedStatePatch[], syncId?: string) => void;
+  authorize: (methodName: string, session: DevframeNodeRpcSession) => boolean;
   /**
-   * Sync IDs that have been applied to the state.
+   * 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.
    */
-  syncIds: Set<string>;
-}
-interface SharedStateEvents<T> {
-  updated: (fullState: T, patches: SharedStatePatch[] | undefined, syncId: string) => void;
-}
-interface SharedStateOptions<T> {
+  onConnect: (connection: DevframeRpcConnection, session: DevframeNodeRpcSession) => void;
   /**
-   * Initial state.
+   * Print the current one-time code and its magic-link URL. Devframe stays
+   * headless — call this yourself once the server is listening. Safe to
+   * call repeatedly; it only prints once per code.
    */
-  initialValue: T;
+  printBanner: () => void;
   /**
-   * Enable patches.
-   *
-   * @default false
+   * 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.
    */
-  enablePatches?: boolean;
+  buildOpenUrl?: (url: string) => string;
 }
-declare function createSharedState<T extends object>(options: SharedStateOptions<T>): SharedState<T>;
 //#endregion
-//#region src/utils/streaming-channel.d.ts
+//#region src/types/diagnostics.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.
+ * The shared diagnostics lookup exposed by the host. A `Proxy` that resolves
+ * any registered code name to its `nostics` handle (a callable that builds
+ * a diagnostic and routes it through registered reporters). Typed loosely
+ * because it spans heterogeneous definitions registered by different
+ * integrations.
  */
-interface StreamErrorPayload {
-  name: string;
-  message: string;
-}
+type DevframeDiagnosticsLogger = Record<string, any>;
 /**
- * Single buffered chunk in the server-side ring buffer.
+ * Host for structured diagnostics — a thin layer over `nostics` that lets
+ * integrations register their own coded errors/warnings into a shared
+ * registry without taking a direct dependency on `nostics`.
  *
- * 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.
+ * Typical usage from a plugin's `setup(ctx)`:
+ *
+ * ```ts
+ * const myDiagnostics = ctx.diagnostics.defineDiagnostics({
+ *   docsBase: 'https://example.com/errors',
+ *   codes: {
+ *     MYP0001: { why: 'Something went wrong' },
+ *   },
+ * })
+ * ctx.diagnostics.register(myDiagnostics)
+ *
+ * // Through the shared lookup (loose typing):
+ * throw ctx.diagnostics.logger.MYP0001()
+ *
+ * // Or directly on the typed handle returned from `defineDiagnostics`:
+ * throw myDiagnostics.MYP0001()
+ * ```
  */
-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 DevframeDiagnosticsHost {
   /**
-   * Size of the per-stream ring buffer kept for replay-on-resubscribe.
-   * `0` (default) disables replay.
+   * Proxy-backed lookup of every registered diagnostic handle by code name.
+   * Resolves to a `nostics` `DiagnosticHandle` — a callable that builds a
+   * diagnostic and routes it through registered reporters; prefix with
+   * `throw` to raise. Loosely typed — for autocompletion, keep a reference
+   * to the typed result of `defineDiagnostics()` instead.
    */
-  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;
+  readonly logger: DevframeDiagnosticsLogger;
   /**
-   * Aborts when the consumer cancels (server-side) or when the transport
-   * loses every subscriber. Producers should poll `signal.aborted` and exit
-   * cleanly.
+   * Register additional diagnostic definitions with this host. After
+   * registration, codes from the new definition are reachable via
+   * `host.logger.CODE`. Plugins that want shared output formatting should
+   * build their diagnostics via `host.defineDiagnostics()` first — that
+   * factory pre-wires the host's ANSI console reporter.
    */
-  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>;
-  /**
-   * Internal — RPC layer subscribes to receive chunk/end notifications.
-   * Not part of the public contract; do not call directly.
-   *
-   * @internal
-   */
-  readonly events: EventEmitter<StreamSinkEvents<T>>;
-  /**
-   * Internal — replay buffer. RPC layer reads on (re)subscribe to feed
-   * missed chunks before going live.
-   *
-   * @internal
-   */
-  readonly buffer: ReadonlyArray<BufferedChunk<T>>;
-}
-interface CreateStreamReaderOptions {
-  id?: string;
-  /**
-   * Maximum number of buffered chunks held client-side while the consumer
-   * isn't draining. On overflow, the oldest chunk is dropped.
-   */
-  highWaterMark?: 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.
-   */
-  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/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
- * a diagnostic and routes it through registered reporters). Typed loosely
- * because it spans heterogeneous definitions registered by different
- * integrations.
- */
-type DevframeDiagnosticsLogger = Record<string, any>;
-/**
- * Host for structured diagnostics — a thin layer over `nostics` that lets
- * integrations register their own coded errors/warnings into a shared
- * registry without taking a direct dependency on `nostics`.
- *
- * Typical usage from a plugin's `setup(ctx)`:
- *
- * ```ts
- * const myDiagnostics = ctx.diagnostics.defineDiagnostics({
- *   docsBase: 'https://example.com/errors',
- *   codes: {
- *     MYP0001: { why: 'Something went wrong' },
- *   },
- * })
- * ctx.diagnostics.register(myDiagnostics)
- *
- * // Through the shared lookup (loose typing):
- * throw ctx.diagnostics.logger.MYP0001()
- *
- * // Or directly on the typed handle returned from `defineDiagnostics`:
- * throw myDiagnostics.MYP0001()
- * ```
- */
-interface DevframeDiagnosticsHost {
-  /**
-   * Proxy-backed lookup of every registered diagnostic handle by code name.
-   * Resolves to a `nostics` `DiagnosticHandle` — a callable that builds a
-   * diagnostic and routes it through registered reporters; prefix with
-   * `throw` to raise. Loosely typed — for autocompletion, keep a reference
-   * to the typed result of `defineDiagnostics()` instead.
-   */
-  readonly logger: DevframeDiagnosticsLogger;
-  /**
-   * Register additional diagnostic definitions with this host. After
-   * registration, codes from the new definition are reachable via
-   * `host.logger.CODE`. Plugins that want shared output formatting should
-   * build their diagnostics via `host.defineDiagnostics()` first — that
-   * factory pre-wires the host's ANSI console reporter.
-   */
-  register: (definitions: Record<string, unknown>) => void;
+  register: (definitions: Record<string, unknown>) => void;
   /**
    * Build a typed diagnostics object with the host's ANSI console reporter
    * pre-wired. The same `devframe/utils/nostics` `defineDiagnostics` every
@@ -620,125 +490,309 @@ interface DevframeHost {
  */
 type DevframeStorageScope = 'workspace' | 'project' | 'global';
 //#endregion
-//#region src/types/views.d.ts
-interface DevframeViewHost {
+//#region src/types/rpc-augments.d.ts
+/**
+ * To be extended
+ */
+interface DevframeRpcClientFunctions {
   /**
+   * Server→client notification that this connection's auth token has been
+   * revoked. The client drops to untrusted on receipt. Broadcast by
+   * `revokeActiveConnectionsForToken`.
+   *
    * @internal
    */
-  buildStaticDirs: {
-    baseUrl: string;
-    source: StaticAssetsSource;
-  }[];
+  'devframe:auth:revoked': () => Promise<void>;
   /**
-   * 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
+   * Streaming chunk pushed from server to subscribed clients. Wired by
+   * `RpcStreamingHost`; do not register manually.
    *
-   * Accepts a local dist directory, or a {@link StaticAssetsSource} remote
-   * declaration served through devframe's caching CDN back-proxy.
+   * @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.
    *
-   * `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.
+   * @internal
    */
-  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.
- */
-type ScopedRpcFn<Registry, NS extends string, T extends string> = `${NS}:${T}` extends keyof Registry ? Extract<Registry[`${NS}:${T}`], AnyRpcFn> : AnyRpcFn;
-/**
- * Augmentable registry mapping a scope namespace to the shape of its
- * persisted settings. Tools augment it so `ctx.scope('my-plugin')`
- * gets a fully-typed `settings.global` / `settings.project`:
- *
- * ```ts
- * declare module 'devframe' {
- *   interface DevframeSettingsRegistry {
- *     'my-plugin': { theme: 'light' | 'dark', recentFiles: string[] }
- *   }
- * }
- * ```
- */
-interface DevframeSettingsRegistry {}
-/**
- * Resolve the settings shape for a namespace from
- * {@link DevframeSettingsRegistry}, falling back to an open record when
- * the namespace hasn't been augmented.
- */
-type SettingsForNamespace<NS extends string> = NS extends keyof DevframeSettingsRegistry ? DevframeSettingsRegistry[NS] extends Record<string, any> ? DevframeSettingsRegistry[NS] : Record<string, any> : Record<string, any>;
-/**
- * A persisted key-value settings store for one scope (`global` or
- * `project`). Backed by a file on the node side and by the shared-state
- * sync protocol on the client, so a `set` on either side propagates to
- * every connected peer and survives restarts.
- *
- * Every method is async because the underlying shared state is resolved
- * lazily on first access.
- */
-interface DevframeSettingsStore<T extends Record<string, any> = Record<string, any>> {
-  /** Read a single setting. Resolves to `undefined` when unset. */
-  get: <K extends keyof T>(key: K) => Promise<T[K] | undefined>;
-  /** Write a single setting. */
-  set: <K extends keyof T>(key: K, value: T[K]) => Promise<void>;
-  /** Remove a single setting. */
-  delete: <K extends keyof T>(key: K) => Promise<void>;
-  /** Read the whole settings object (immutable snapshot). */
-  all: () => Promise<Readonly<T>>;
+  'devframe:streaming:end': (channel: string, id: string, error?: {
+    name: string;
+    message: string;
+  }) => Promise<void>;
   /**
-   * Subscribe to settings changes. Resolves to an unsubscribe function.
-   * Fires on every local or remote mutation with the full snapshot.
+   * Server→client cancel for an in-flight upload. Wired by
+   * `RpcStreamingHost`; do not register manually.
+   *
+   * @internal
    */
-  onChange: (fn: (value: Readonly<T>) => void) => Promise<() => void>;
-}
-/**
- * The two settings scopes available on a scoped context.
- *
- *   - `project` — per-workspace state, persisted under the host's
- *     `workspace` storage dir. Project-local settings.
- *   - `global`  — per-user state, persisted under the host's `global`
- *     storage dir. Machine-wide preferences.
- */
-interface DevframeSettings<T extends Record<string, any> = Record<string, any>> {
-  global: DevframeSettingsStore<T>;
-  project: DevframeSettingsStore<T>;
+  'devframe:streaming:upload-cancel': (channel: string, id: string) => Promise<void>;
+  /**
+   * Full shared-state snapshot pushed from server to subscribed clients.
+   * Wired by `RpcSharedStateHost`; do not register manually.
+   *
+   * @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.
+   *
+   * @internal
+   */
+  'devframe:rpc:client-state:patch': (key: string, patches: any[], syncId: string) => Promise<void>;
 }
 /**
- * Map the server-side RPC registry down to the bare names owned by a
- * namespace, so a scoped `call('get-cwd')` is typed without the
- * `my-plugin:` prefix.
- */
-type ScopedServerFunctions<NS extends string> = { [K in keyof DevframeRpcServerFunctions as K extends `${NS}:${infer R}` ? R : never]: DevframeRpcServerFunctions[K]; };
-/**
- * Map the client-side RPC registry down to the bare names owned by a
- * namespace, used by scoped `broadcast`.
- */
-type ScopedClientFunctions<NS extends string> = { [K in keyof DevframeRpcClientFunctions as K extends `${NS}:${infer R}` ? R : never]: DevframeRpcClientFunctions[K]; };
-/**
- * Map the shared-state registry down to the bare keys owned by a
- * namespace, so scoped `sharedState('messages')` is typed without the
- * `my-plugin:` prefix.
- */
-type ScopedSharedStates<NS extends string> = { [K in keyof DevframeRpcSharedStates as K extends `${NS}:${infer R}` ? R : never]: DevframeRpcSharedStates[K]; };
-/**
- * Broadcast options for a scoped client method (bare name).
+ * To be extended
  */
-interface ScopedBroadcastOptions<METHOD, Args extends any[]> {
-  method: METHOD;
-  args: Args;
-  optional?: boolean;
-  event?: boolean;
-}
+interface DevframeRpcServerFunctions {
+  /**
+   * 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;
+  }>;
+  /**
+   * 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 {
+  /**
+   * @internal
+   */
+  buildStaticDirs: {
+    baseUrl: string;
+    source: StaticAssetsSource;
+  }[];
+  /**
+   * 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.
+ */
+type ScopedRpcFn<Registry, NS extends string, T extends string> = `${NS}:${T}` extends keyof Registry ? Extract<Registry[`${NS}:${T}`], AnyRpcFn> : AnyRpcFn;
+/**
+ * Augmentable registry mapping a scope namespace to the shape of its
+ * persisted settings. Tools augment it so `ctx.scope('my-plugin')`
+ * gets a fully-typed `settings.global` / `settings.project`:
+ *
+ * ```ts
+ * declare module 'devframe' {
+ *   interface DevframeSettingsRegistry {
+ *     'my-plugin': { theme: 'light' | 'dark', recentFiles: string[] }
+ *   }
+ * }
+ * ```
+ */
+interface DevframeSettingsRegistry {}
+/**
+ * Resolve the settings shape for a namespace from
+ * {@link DevframeSettingsRegistry}, falling back to an open record when
+ * the namespace hasn't been augmented.
+ */
+type SettingsForNamespace<NS extends string> = NS extends keyof DevframeSettingsRegistry ? DevframeSettingsRegistry[NS] extends Record<string, any> ? DevframeSettingsRegistry[NS] : Record<string, any> : Record<string, any>;
+/**
+ * A persisted key-value settings store for one scope (`global` or
+ * `project`). Backed by a file on the node side and by the shared-state
+ * sync protocol on the client, so a `set` on either side propagates to
+ * every connected peer and survives restarts.
+ *
+ * Every method is async because the underlying shared state is resolved
+ * lazily on first access.
+ */
+interface DevframeSettingsStore<T extends Record<string, any> = Record<string, any>> {
+  /** Read a single setting. Resolves to `undefined` when unset. */
+  get: <K extends keyof T>(key: K) => Promise<T[K] | undefined>;
+  /** Write a single setting. */
+  set: <K extends keyof T>(key: K, value: T[K]) => Promise<void>;
+  /** Remove a single setting. */
+  delete: <K extends keyof T>(key: K) => Promise<void>;
+  /** Read the whole settings object (immutable snapshot). */
+  all: () => Promise<Readonly<T>>;
+  /**
+   * Subscribe to settings changes. Resolves to an unsubscribe function.
+   * Fires on every local or remote mutation with the full snapshot.
+   */
+  onChange: (fn: (value: Readonly<T>) => void) => Promise<() => void>;
+}
+/**
+ * The two settings scopes available on a scoped context.
+ *
+ *   - `project` — per-workspace state, persisted under the host's
+ *     `workspace` storage dir. Project-local settings.
+ *   - `global`  — per-user state, persisted under the host's `global`
+ *     storage dir. Machine-wide preferences.
+ */
+interface DevframeSettings<T extends Record<string, any> = Record<string, any>> {
+  global: DevframeSettingsStore<T>;
+  project: DevframeSettingsStore<T>;
+}
+/**
+ * Map the server-side RPC registry down to the bare names owned by a
+ * namespace, so a scoped `call('get-cwd')` is typed without the
+ * `my-plugin:` prefix.
+ */
+type ScopedServerFunctions<NS extends string> = { [K in keyof DevframeRpcServerFunctions as K extends `${NS}:${infer R}` ? R : never]: DevframeRpcServerFunctions[K]; };
+/**
+ * Map the client-side RPC registry down to the bare names owned by a
+ * namespace, used by scoped `broadcast`.
+ */
+type ScopedClientFunctions<NS extends string> = { [K in keyof DevframeRpcClientFunctions as K extends `${NS}:${infer R}` ? R : never]: DevframeRpcClientFunctions[K]; };
+/**
+ * Map the shared-state registry down to the bare keys owned by a
+ * namespace, so scoped `sharedState('messages')` is typed without the
+ * `my-plugin:` prefix.
+ */
+type ScopedSharedStates<NS extends string> = { [K in keyof DevframeRpcSharedStates as K extends `${NS}:${infer R}` ? R : never]: DevframeRpcSharedStates[K]; };
+/**
+ * Broadcast options for a scoped client method (bare name).
+ */
+interface ScopedBroadcastOptions<METHOD, Args extends any[]> {
+  method: METHOD;
+  args: Args;
+  optional?: boolean;
+  event?: boolean;
+}
 /**
  * Node-side streaming host scoped to a namespace. Channel names are
  * auto-prefixed with `<namespace>:`.
@@ -1023,1014 +1077,989 @@ interface DevframeServicesHost {
   ready: () => Promise<void>;
 }
 //#endregion
-//#region src/types/rpc-augments.d.ts
+//#region src/types/devframe.d.ts
 /**
- * To be extended
+ * 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 `/`.
  */
-interface DevframeRpcClientFunctions {
-  /**
-   * 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>;
+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 {
   /**
-   * Streaming chunk pushed from server to subscribed clients. Wired by
-   * `RpcStreamingHost`; do not register manually.
-   *
-   * @internal
+   * Upgrade route segment the socket binds to and is advertised at, relative
+   * to the SPA base. Default: `__ws`.
    */
-  'devframe:streaming:chunk': (channel: string, id: string, seq: number, chunk: any) => Promise<void>;
+  route?: string;
   /**
-   * Streaming terminator pushed from server to subscribed clients. Wired by
-   * `RpcStreamingHost`; do not register manually.
-   *
-   * @internal
+   * 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}.
    */
-  'devframe:streaming:end': (channel: string, id: string, error?: {
-    name: string;
-    message: string;
-  }) => Promise<void>;
+  port?: number;
   /**
-   * Server→client cancel for an in-flight upload. Wired by
-   * `RpcStreamingHost`; do not register manually.
-   *
-   * @internal
+   * 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.
    */
-  'devframe:streaming:upload-cancel': (channel: string, id: string) => Promise<void>;
+  sidecar?: boolean;
   /**
-   * Full shared-state snapshot pushed from server to subscribed clients.
-   * Wired by `RpcSharedStateHost`; do not register manually.
-   *
-   * @internal
+   * Advertise a fixed, fully-qualified endpoint on another origin (a full
+   * `ws://`/`wss://` URL). Takes precedence over `port`/`route` in the meta.
    */
-  'devframe:rpc:client-state:updated': (key: string, fullState: any, syncId: string) => Promise<void>;
+  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 {
   /**
-   * Incremental shared-state patch pushed from server to subscribed clients.
-   * Wired by `RpcSharedStateHost`; do not register manually.
-   *
-   * @internal
+   * Route segment the SSE endpoint binds to and is advertised at, relative
+   * to the SPA base. Default: `__sse`.
    */
-  'devframe:rpc:client-state:patch': (key: string, patches: any[], syncId: string) => Promise<void>;
+  route?: string;
 }
 /**
- * To be extended
+ * Configuration for the route-based MCP server mounted alongside the dev
+ * server (opt-in 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 DevframeRpcServerFunctions {
+interface McpRouteOptions {
   /**
-   * 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
+   * Route segment the MCP endpoint binds to, relative to the SPA base.
+   * Default: `__mcp` (i.e. `/__mcp` standalone, `/__<id>/__mcp` hosted).
    */
-  'anonymous:devframe:auth': (params: {
-    authToken: string;
-    ua: string;
-    origin: string;
-  }) => Promise<{
-    isTrusted: boolean;
-  }>;
+  path?: string;
   /**
-   * 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.
+   * 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.
    *
-   * @internal
+   * 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).
    */
-  'anonymous:devframe:auth:exchange': (params: {
-    code: string;
-    ua: string;
-    origin: string;
-  }) => Promise<{
-    authToken: string | null;
-  }>;
+  allowedOrigins?: readonly string[] | false;
+}
+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;
   /**
-   * 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
+   * 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.
    */
-  'devframe:auth:revoke': () => Promise<void>;
+  open?: boolean | string;
   /**
-   * Subscribe a client to a shared-state key. Wired by
-   * `RpcSharedStateHost`; do not register manually.
+   * Authentication for the standalone dev server.
    *
-   * @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.
+   *   - `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.
    *
-   * @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.
+   * Hosted adapters (`vite`, `embedded`) ignore this and defer to the host's
+   * auth; `@vitejs/devtools` honors the equivalent `devtools.clientAuth`.
    *
-   * @internal
+   * @default true
    */
-  'devframe:rpc:server-state:set': (key: string, value: any, syncId: string) => Promise<void>;
+  auth?: boolean | DevframeAuthHandler;
   /**
-   * Apply a patch to a shared-state value (from the client). Wired by
-   * `RpcSharedStateHost`; do not register manually.
+   * Expose a route-based MCP server alongside the dev server, speaking the
+   * MCP Streamable-HTTP transport at `/__mcp` (relative to the base path).
+   * It surfaces the same `ctx.agent` tools + shared-state resources as the
+   * stdio `mcp` command, but against the live, running server.
    *
-   * @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.
+   * - `false` / omitted (default) — no MCP route is mounted.
+   * - `true` — mount at the default `__mcp` route with the loopback-only
+   *   origin gate.
+   * - {@link McpRouteOptions} — customise the route path / allowed origins.
    *
-   * @internal
+   * The `--mcp` / `--no-mcp` CLI flags override this per run.
    */
-  'devframe:streaming:subscribe': (channel: string, id: string, opts?: {
-    afterSeq?: number;
-  }) => Promise<void>;
+  mcp?: boolean | McpRouteOptions;
   /**
-   * Client→server streaming unsubscribe. Wired by `RpcStreamingHost`;
-   * do not register manually.
-   *
-   * @internal
+   * 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.
    */
-  'devframe:streaming:unsubscribe': (channel: string, id: string) => Promise<void>;
+  distDir?: StaticAssetsSource;
   /**
-   * Client→server streaming cancellation request. Wired by
-   * `RpcStreamingHost`; do not register manually.
-   *
-   * @internal
+   * 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'`).
    */
-  'devframe:streaming:cancel': (channel: string, id: string) => Promise<void>;
+  ws?: DevframeWsOptions | false;
   /**
-   * Client→server upload chunk. Wired by `RpcStreamingHost`; do not
-   * register manually.
-   *
-   * @internal
+   * 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.
    */
-  'devframe:streaming:upload-chunk': (channel: string, id: string, seq: number, chunk: any) => Promise<void>;
+  sse?: boolean | DevframeSseOptions;
   /**
-   * 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.
+   * 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.
    */
-  'devframe:services': DevframeServicesState;
-}
-//#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> & {
+  configure?: (cli: CAC) => void;
   /**
-   * Invoke a locally registered server RPC function directly.
+   * 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 })`.
    *
-   * 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
-   */
-  broadcast: <T extends keyof DevframeRpcClientFunctions, Args extends Parameters<DevframeRpcClientFunctions[T]>>(options: RpcBroadcastOptions<T, Args>) => Promise<void>;
-  /**
-   * Get the current RPC client
+   * Use {@link defineCliFlags} to preserve the literal schema-map
+   * shape, and {@link InferCliFlags} to recover the typed output at the
+   * call site:
    *
-   * Available in RPC functions to get the current RPC client
+   * ```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>
+   *   },
+   * })
+   * ```
    */
-  getCurrentRpcSession: () => DevframeNodeRpcSession | undefined;
+  flags?: CliFlagsSchema;
+}
+/**
+ * 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.
+ */
+interface DevframeDockDefaults {
+  /** Dock entry title. Defaults to the definition's `name`. */
+  title?: string;
+  /** Dock entry icon. Defaults to the definition's `icon`. */
+  icon?: string | {
+    light: string;
+    dark: string;
+  };
   /**
-   * The shared state host
+   * Sort weight within the dock; higher sorts earlier.
+   * @default 0
    */
-  sharedState: RpcSharedStateHost;
+  defaultOrder?: number;
   /**
-   * The streaming channel host. Provides per-channel `start()` /
-   * `pipeFrom()` producers; clients consume via `rpc.streaming.subscribe()`.
-   *
-   * @see RpcStreamingHost
+   * Category the entry groups under in the dock.
+   * @default 'default'
    */
-  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[];
+  category?: 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.
+   * Conditional-visibility expression (same syntax as command `when`
+   * clauses). Set to `'false'` to hide the entry unconditionally.
    */
-  onKeyAdded: (fn: (key: string) => void) => () => void;
+  when?: 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.
+   * 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.
    */
-  delete: (key: string) => boolean;
+  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;
 }
 /**
- * Options for `RpcStreamingHost.create()`.
+ * 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 RpcStreamingChannelOptions {
+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;
   /**
-   * 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.
+   * `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.
    *
-   * The buffer is per stream id, not per channel — each `channel.start()`
-   * gets its own.
+   * - **Remote assets** — becomes the default `resolveFrom` for any remote
+   *   {@link StaticAssetsSource} the devframe hosts (its `cli.distDir`, 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.
    */
-  replayWindow?: number;
+  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;
+  };
   /**
-   * 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.
+   * 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.
    *
-   * 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.
+   * @see {@link DevframeDockDefaults}
    */
-  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;
+  dock?: DevframeDockDefaults;
   /**
-   * 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.
+   * Mount path override. Defaults depend on the adapter:
+   * `/` for standalone (`cli` / `build`), `/__<id>/` for hosted
+   * (`vite` / `embedded`).
    */
-  start: (opts?: {
-    id?: string;
-  }) => StreamSink<T>;
+  basePath?: string;
   /**
-   * Convenience: start a stream and pipe a `ReadableStream<T>` into it.
-   * The pipe uses `sink.signal` so cancellation propagates upstream.
+   * 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.
    *
-   * Node-stream interop: convert a `Readable` with `Readable.toWeb(node)`
-   * before passing it here.
+   * @default 'warn'
    */
-  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[];
+  duplicationStrategy?: DevframeDuplicationStrategy;
   /**
-   * 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 }
-   * }
-   * ```
+   * Declares which runtimes meaningfully support this devframe. Adapters
+   * act on a `false` before doing any work:
    *
-   * Calling `reader.cancel()` on the server sends an `upload-cancel` to
-   * the uploading client, which aborts its sink.
+   * - `build: false` — `createCac` skips registering the `build` subcommand,
+   *   and `createBuild` refuses (throws `DF0042`) unless `{ force: true }`.
+   *   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).
    */
-  openInbound: (opts?: {
-    id?: string;
-  }) => StreamReader<T>;
+  capabilities?: {
+    dev?: boolean;
+    build?: boolean;
+  };
+  /**
+   * Wire services this devframe consumes (see `DevframeServiceDefinition`).
+   * Each entry is either a declarative descriptor
+   * (`{ package, version?, required?, options? }` — 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.
+   */
+  services?: DevframeServiceInput[];
+  /** 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 {
+  /**
+   * 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`.
+   *
+   * 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.
+   */
+  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[])[]>);
 /**
- * Server-side streaming host. Lives on `ctx.rpc.streaming` alongside
- * `ctx.rpc.sharedState`. Each named channel owns its own stream registry
- * and wire namespace.
+ * One {@link DevframeRpcOptions.snapshot} entry: a bare method id (bakes
+ * the no-argument call) or a method plus the argument-tuples to bake.
  */
-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;
-}
+type DevframeSnapshotRpcEntry = string | {
+  method: string;
+  inputs: DevframeSnapshotRpcInputs;
+};
 //#endregion
-//#region src/types/context.d.ts
-interface DevframeCapabilities {
-  rpc?: boolean;
-  views?: boolean;
+//#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.
+ */
+interface SharedStatePatch {
+  op: 'add' | 'remove' | 'replace';
+  path: readonly (string | number)[];
+  value?: unknown;
 }
 /**
- * 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.
+ * State host that is immutable by default with explicit mutate.
  */
-interface DevframeNodeContext {
-  readonly workspaceRoot: string;
-  readonly cwd: string;
+interface SharedState<T> {
   /**
-   * 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.
+   * Get the current state. Immutable.
    */
-  readonly mode: 'dev' | 'build';
+  value: () => Immutable<T>;
   /**
-   * Host runtime abstraction — exposes `mountStatic` / `resolveOrigin` /
-   * `getStorageDir`.
+   * Subscribe to state changes.
    */
-  host: DevframeHost;
-  rpc: RpcFunctionsHost;
-  views: DevframeViewHost;
+  on: EventEmitter<SharedStateEvents<T>>['on'];
   /**
-   * Structured diagnostics host — wraps `nostics` and lets integrations
-   * register their own coded errors/warnings into the shared lookup.
+   * Mutate the state.
    */
-  diagnostics: DevframeDiagnosticsHost;
+  mutate: (fn: (state: T) => void, syncId?: string) => void;
   /**
-   * Agent host — aggregates the agent-exposed surface of this devtool.
+   * Apply patches to the state.
    */
-  agent: DevframeAgentHost;
+  patch: (patches: SharedStatePatch[], syncId?: string) => void;
   /**
-   * 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.
+   * Sync IDs that have been applied to the state.
    */
-  services: DevframeServicesHost;
+  syncIds: Set<string>;
+}
+interface SharedStateEvents<T> {
+  updated: (fullState: T, patches: SharedStatePatch[] | undefined, syncId: string) => void;
+}
+interface SharedStateOptions<T> {
   /**
-   * 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 — 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 },
-   * }
-   * ```
+   * Initial state.
    */
-  staticConfig: Partial<DevframeConnectionConfigsRegistry>;
+  initialValue: T;
   /**
-   * 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.
+   * Enable patches.
    *
-   * Pass `null` or `''` to un-scope and get the base context.
+   * @default false
    */
-  scope: {
-    <NS extends string>(namespace: NS): DevframeScopedNodeContext<NS, SettingsForNamespace<NS>>;
-    (namespace?: null | ''): DevframeNodeContext;
-  };
+  enablePatches?: boolean;
+}
+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.
+ */
+interface StreamErrorPayload {
+  name: string;
+  message: string;
 }
 /**
- * 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.
+ * Single buffered chunk in the server-side ring buffer.
  *
- * 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.
+ * 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 ConnectionMetaWebsocket {
+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;
   /**
-   * 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.
+   * Size of the per-stream ring buffer kept for replay-on-resubscribe.
+   * `0` (default) disables replay.
    */
-  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;
+  replayWindow?: number;
 }
 /**
- * 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.
+ * 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 ConnectionMetaSse {
-  /**
-   * Path to the SSE endpoint. Relative paths (the default, e.g. `__sse`)
-   * are resolved against `__connection.json`'s location; absolute paths
-   * (`/__sse`) resolve against the page origin.
-   */
-  path?: string;
-  /** Override the port. Combined with the page hostname unless `host` is set. */
-  port?: number;
-  /** Override the host (`hostname[:port]`). Use for a fully cross-origin endpoint. */
-  host?: string;
-}
-interface ConnectionMeta {
-  /**
-   * The server's primary live-RPC transport (`websocket` / `sse`), `static`
-   * for a pre-computed RPC dump with no live server, or `none` for a server
-   * exposing no RPC transport at all (e.g. an MCP-only deployment).
-   */
-  backend: 'websocket' | 'sse' | 'static' | 'none';
-  /**
-   * WebSocket endpoint, resolved by the client into a `ws(s)://` URL:
-   *
-   *   - {@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.
-   */
-  websocket?: number | string | ConnectionMetaWebsocket;
-  /**
-   * SSE endpoint (`GET` opens the event stream, `POST` carries RPC calls),
-   * resolved by the client into an `http(s)://` URL with the same
-   * proxy-safe rules as {@link ConnectionMeta.websocket}:
-   *
-   *   - {@link ConnectionMetaSse} — the proxy-flexible default; a
-   *     same-origin path relative to `__connection.json`.
-   *   - `string` — a full `http(s)://` URL used verbatim, or a path
-   *     resolved same-origin.
-   */
-  sse?: string | ConnectionMetaSse;
-  /**
-   * Present when the dev server exposes a route-based MCP endpoint
-   * (`cli.mcp`). Advertises the MCP Streamable-HTTP route so in-browser
-   * 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}.
-   */
-  mcp?: {
-    path: string;
-    port?: number;
-  };
+interface StreamSink<T> {
+  /** Stable id used by clients to subscribe. */
+  readonly id: 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.
+   * Aborts when the consumer cancels (server-side) or when the transport
+   * loses every subscriber. Producers should poll `signal.aborted` and exit
+   * cleanly.
    */
-  jsonSerializableMethods?: string[];
+  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>;
   /**
-   * Absolute URL of the `__connection.json` this meta was loaded from.
-   * Annotated by the client (not served) 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.
+   * Internal — RPC layer subscribes to receive chunk/end notifications.
+   * Not part of the public contract; do not call directly.
+   *
+   * @internal
    */
-  baseUrl?: string;
+  readonly events: EventEmitter<StreamSinkEvents<T>>;
   /**
-   * 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.
+   * Internal — replay buffer. RPC layer reads on (re)subscribe to feed
+   * missed chunks before going live.
    *
-   * > [!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`.
+   * @internal
    */
-  authToken?: string;
+  readonly buffer: ReadonlyArray<BufferedChunk<T>>;
+}
+interface CreateStreamReaderOptions {
+  id?: string;
   /**
-   * 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.
-   *
-   * Treat this as a bearer credential. Keep connection metadata containing the
-   * token same-origin until the requesting origin has been verified.
+   * Maximum number of buffered chunks held client-side while the consumer
+   * isn't draining. On overflow, the oldest chunk is dropped.
    */
-  viewerOriginToken?: string;
+  highWaterMark?: number;
   /**
-   * 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' }
-   *   }
-   * }
-   * ```
+   * 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.
    */
-  configs?: Partial<DevframeConnectionConfigsRegistry>;
+  onOverflow?: (dropped: number) => void;
+  /** Called when the consumer cancels — the RPC layer sends `:cancel` upstream. */
+  onCancel?: () => void;
 }
 /**
- * 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`.
+ * 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 DevframeConnectionConfigsRegistry {}
-//#endregion
-//#region src/node/auth/handler.d.ts
+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;
+}
 /**
- * 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.
+ * 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 DevframeAuthHandler {
+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> & {
   /**
-   * `anonymous:devframe:auth` + `anonymous:devframe:auth:exchange` (the
-   * handshake) and `devframe:auth:revoke` (self-revoke) — register these on
-   * the RPC host (e.g. `rpcHost.register(fn)` for each).
+   * Invoke a locally registered server RPC function directly.
+   *
+   * This bypasses transport and is useful for server-side cross-function calls.
    */
-  rpcFunctions: RpcFunctionDefinitionAny[];
+  invokeLocal: <T extends keyof DevframeRpcServerFunctions, Args extends Parameters<DevframeRpcServerFunctions[T]>>(method: T, ...args: Args) => Promise<Awaited<ReturnType<DevframeRpcServerFunctions[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.
+   * Broadcast a message to all connected clients
    */
-  authorize: (methodName: string, session: DevframeNodeRpcSession) => boolean;
+  broadcast: <T extends keyof DevframeRpcClientFunctions, Args extends Parameters<DevframeRpcClientFunctions[T]>>(options: RpcBroadcastOptions<T, Args>) => Promise<void>;
   /**
-   * 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.
+   * Get the current RPC client
+   *
+   * Available in RPC functions to get the current RPC client
    */
-  onConnect: (connection: DevframeRpcConnection, session: DevframeNodeRpcSession) => void;
+  getCurrentRpcSession: () => DevframeNodeRpcSession | undefined;
   /**
-   * Print the current one-time code and its magic-link URL. Devframe stays
-   * headless — call this yourself once the server is listening. Safe to
-   * call repeatedly; it only prints once per code.
+   * The shared state host
    */
-  printBanner: () => void;
+  sharedState: RpcSharedStateHost;
   /**
-   * 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.
+   * The streaming channel host. Provides per-channel `start()` /
+   * `pipeFrom()` producers; clients consume via `rpc.streaming.subscribe()`.
+   *
+   * @see RpcStreamingHost
    */
-  buildOpenUrl?: (url: string) => string;
+  streaming: RpcStreamingHost;
+};
+interface RpcSharedStateGetOptions<T> {
+  sharedState?: SharedState<T>;
+  initialValue?: T;
 }
-//#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.
- */
-interface DevframeWsOptions {
+interface RpcSharedStateHost {
+  get: <T extends object = any>(key: string, options?: RpcSharedStateGetOptions<T>) => Promise<SharedState<T>>;
+  keys: () => string[];
   /**
-   * Upgrade route segment the socket binds to and is advertised at, relative
-   * to the SPA base. Default: `__ws`.
+   * 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.
    */
-  route?: string;
+  onKeyAdded: (fn: (key: string) => void) => () => 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}.
+   * 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.
    */
-  port?: number;
+  delete: (key: string) => boolean;
+}
+/**
+ * Options for `RpcStreamingHost.create()`.
+ */
+interface RpcStreamingChannelOptions {
   /**
-   * 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.
+   * 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.
    */
-  sidecar?: boolean;
+  replayWindow?: number;
   /**
-   * Advertise a fixed, fully-qualified endpoint on another origin (a full
-   * `ws://`/`wss://` URL). Takes precedence over `port`/`route` in the meta.
+   * 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.
+   *
+   * 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.
    */
-  url?: string;
+  closedStreamRetention?: number;
 }
 /**
- * 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'`).
+ * 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 DevframeSseOptions {
+interface RpcStreamingChannel<T = unknown> {
+  /** Channel name as registered with `ctx.rpc.streaming.create()`. */
+  readonly name: string;
   /**
-   * Route segment the SSE endpoint binds to and is advertised at, relative
-   * to the SPA base. Default: `__sse`.
+   * 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.
    */
-  route?: string;
-}
-/**
- * Configuration for the route-based MCP server mounted alongside the dev
- * server (opt-in 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 {
+  start: (opts?: {
+    id?: string;
+  }) => StreamSink<T>;
   /**
-   * Route segment the MCP endpoint binds to, relative to the SPA base.
-   * Default: `__mcp` (i.e. `/__mcp` standalone, `/__<id>/__mcp` hosted).
+   * 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.
    */
-  path?: string;
+  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[];
   /**
-   * 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.
+   * 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:
    *
-   * 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).
+   * ```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.
    */
-  allowedOrigins?: readonly string[] | false;
+  openInbound: (opts?: {
+    id?: string;
+  }) => StreamReader<T>;
 }
-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;
+/**
+ * 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 {
   /**
-   * 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.
+   * 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.
    */
-  open?: boolean | string;
+  create: <T = unknown>(name: string, opts?: RpcStreamingChannelOptions) => RpcStreamingChannel<T>;
   /**
-   * 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.
-   *
-   * Hosted adapters (`vite`, `embedded`) ignore this and defer to the host's
-   * auth; `@vitejs/devtools` honors the equivalent `devtools.clientAuth`.
+   * 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.
    *
-   * @default true
+   * @internal
    */
-  auth?: boolean | DevframeAuthHandler;
+  _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;
   /**
-   * Expose a route-based MCP server alongside the dev server, speaking the
-   * MCP Streamable-HTTP transport at `/__mcp` (relative to the base path).
-   * It surfaces the same `ctx.agent` tools + shared-state resources as the
-   * stdio `mcp` command, but against the live, running server.
+   * Lifecycle distinction surfaced to plugin authors:
    *
-   * - `false` / omitted (default) — no MCP route is mounted.
-   * - `true` — mount at the default `__mcp` route with the loopback-only
-   *   origin gate.
-   * - {@link McpRouteOptions} — customise the route path / allowed origins.
+   *   - `'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.
    *
-   * The `--mcp` / `--no-mcp` CLI flags override this per run.
+   * 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.
    */
-  mcp?: boolean | McpRouteOptions;
+  readonly mode: 'dev' | 'build';
   /**
-   * 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.
+   * Host runtime abstraction — exposes `mountStatic` / `resolveOrigin` /
+   * `getStorageDir`.
    */
-  distDir?: StaticAssetsSource;
+  host: DevframeHost;
+  rpc: RpcFunctionsHost;
+  views: DevframeViewHost;
   /**
-   * 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'`).
+   * Structured diagnostics host — wraps `nostics` and lets integrations
+   * register their own coded errors/warnings into the shared lookup.
    */
-  ws?: DevframeWsOptions | false;
+  diagnostics: DevframeDiagnosticsHost;
   /**
-   * 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 host — aggregates the agent-exposed surface of this devtool.
    */
-  sse?: boolean | DevframeSseOptions;
+  agent: DevframeAgentHost;
   /**
-   * 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.
+   * 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.
    */
-  configure?: (cli: CAC) => void;
+  services: DevframeServicesHost;
   /**
-   * 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:
+   * 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 — it's serialized
+   * once, after setup, and changing it afterwards reaches no client.
    *
    * ```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>
-   *   },
-   * })
+   * ctx.staticConfig.dock = {
+   *   ...ctx.staticConfig.dock,
+   *   categoryOrder: { ...ctx.staticConfig.dock?.categoryOrder, ...myOrder },
+   * }
    * ```
    */
-  flags?: CliFlagsSchema;
+  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.
+   *
+   * Pass `null` or `''` to un-scope and get the base context.
+   */
+  scope: {
+    <NS extends string>(namespace: NS): DevframeScopedNodeContext<NS, SettingsForNamespace<NS>>;
+    (namespace?: null | ''): DevframeNodeContext;
+  };
 }
 /**
- * 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`.
+ * 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.
  *
- * 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.
+ * 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 DevframeDockDefaults {
-  /** Dock entry title. Defaults to the definition's `name`. */
-  title?: string;
-  /** Dock entry icon. Defaults to the definition's `icon`. */
-  icon?: string | {
-    light: string;
-    dark: string;
-  };
+interface ConnectionMetaWebsocket {
   /**
-   * Sort weight within the dock; higher sorts earlier.
-   * @default 0
+   * 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.
    */
-  defaultOrder?: 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;
+}
+/**
+ * Object form of {@link ConnectionMeta.sse} — the same proxy-safe shape and
+ * resolution rules as {@link ConnectionMetaWebsocket}, producing an
+ * `http(s)://` endpoint instead of a `ws(s)://` one. Set `port` (and/or
+ * `host`) only when the SSE endpoint genuinely lives on a different origin
+ * than the page, e.g. a side-car server on its own port.
+ */
+interface ConnectionMetaSse {
   /**
-   * Category the entry groups under in the dock.
-   * @default 'default'
+   * 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.
    */
-  category?: string;
+  path?: string;
+  /** Override the port. Combined with the page hostname unless `host` is set. */
+  port?: number;
+  /** Override the host (`hostname[:port]`). Use for a fully cross-origin endpoint. */
+  host?: string;
+}
+interface ConnectionMeta {
   /**
-   * Conditional-visibility expression (same syntax as command `when`
-   * clauses). Set to `'false'` to hide the entry unconditionally.
+   * 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).
    */
-  when?: string;
+  backend: 'websocket' | 'sse' | 'static' | 'none';
   /**
-   * 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.
+   * WebSocket endpoint, resolved by the client into a `ws(s)://` URL:
+   *
+   *   - {@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.
    */
-  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;
-}
-/**
- * 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;
+  websocket?: number | string | ConnectionMetaWebsocket;
   /**
-   * `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 `cli.distDir`, 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.
+   * 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}:
    *
-   * Optional for backward compatibility; omitting it falls back to
-   * runtime-directory resolution and disables the zero-network installed-copy
-   * fast paths above.
+   *   - {@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.
    */
-  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?: string | ConnectionMetaSse;
+  /**
+   * Present when the dev server exposes a route-based MCP endpoint
+   * (`cli.mcp`). 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}.
+   */
+  mcp?: {
+    path: string;
+    port?: number;
   };
   /**
-   * 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}
+   * 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.
    */
-  dock?: DevframeDockDefaults;
+  jsonSerializableMethods?: string[];
   /**
-   * Mount path override. Defaults depend on the adapter:
-   * `/` for standalone (`cli` / `build`), `/__<id>/` for hosted
-   * (`vite` / `embedded`).
+   * Absolute URL of the `__connection.json` this meta was loaded from.
+   * Annotated by the client (not served) 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.
    */
-  basePath?: string;
+  baseUrl?: string;
   /**
-   * 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.
+   * 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.
    *
-   * @default 'warn'
+   * > [!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`.
    */
-  duplicationStrategy?: DevframeDuplicationStrategy;
+  authToken?: string;
   /**
-   * Declares which runtimes meaningfully support this devframe. Adapters
-   * act on a `false` before doing any work:
+   * 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.
    *
-   * - `build: false` — `createCac` skips registering the `build` subcommand,
-   *   and `createBuild` refuses (throws `DF0042`) unless `{ force: true }`.
-   *   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).
+   * Treat this as a bearer credential. Keep connection metadata containing the
+   * token same-origin until the requesting origin has been verified.
    */
-  capabilities?: {
-    dev?: boolean;
-    build?: boolean;
-  };
+  viewerOriginToken?: string;
   /**
-   * Wire services this devframe consumes (see `DevframeServiceDefinition`).
-   * Each entry is either a declarative descriptor
-   * (`{ package, version?, required?, options? }` — 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.
+   * 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' }
+   *   }
+   * }
+   * ```
    */
-  services?: DevframeServiceInput[];
-  /** Server-side setup — the primary entrypoint. Runs in every runtime. */
-  setup: (ctx: DevframeNodeContext, info?: DevframeSetupInfo) => void | Promise<void>;
-  cli?: DevframeCliOptions;
+  configs?: Partial<DevframeConnectionConfigsRegistry>;
 }
+/**
+ * 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 DevframeConnectionConfigsRegistry {}
 //#endregion
-export { DevframeStorageScope as $, DevframeServiceId as A, DevframeAgentHost as At, DevframeScopedNodeRpc as B, RpcStreamingChannelOptions as C, AgentResource as Ct, DevframeRpcSharedStates as D, AgentToolInput as Dt, DevframeRpcServerFunctions as E, AgentTool as Et, DevframeServicesHost as F, CliFlagsSchema as Ft, ScopedBroadcastOptions as G, DevframeSettings as H, DevframeServicesRegistry as I, InferCliFlags as It, ScopedServerFunctions as J, ScopedClientFunctions as K, DevframeServicesScopeRegistry as L, defineCliFlags as Lt, DevframeServiceMeta as M, EventEmitter as Mt, DevframeServiceOf as N, EventUnsubscribe as Nt, DevframeServiceDefinition as O, AgentToolProvider as Ot, DevframeServiceScopeOf as P, EventsMap as Pt, DevframeHost as Q, DevframeServicesState as R, parseCliFlags as Rt, RpcStreamingChannel as S, AgentManifest as St, DevframeRpcClientFunctions as T, AgentResourceInput as Tt, DevframeSettingsRegistry as U, DevframeScopedStreamingHost as V, DevframeSettingsStore as W, SettingsForNamespace as X, ScopedSharedStates as Y, DevframeViewHost as Z, DevframeNodeRpcSession as _, SharedStateEvents as _t, DevframeDuplicationStrategy as a, StreamErrorPayload as at, RpcSharedStateGetOptions as b, createSharedState as bt, DevframeWsOptions as c, StreamSinkEvents as ct, ConnectionMeta as d, Immutable as dt, DevframeDiagnosticsHost as et, ConnectionMetaSse as f, ImmutableArray as ft, DevframeNodeContext as g, SharedState as gt, DevframeConnectionConfigsRegistry as h, ImmutableSet as ht, DevframeDockDefaults as i, CreateStreamSinkOptions as it, DevframeServiceInput as j, DevframeAgentHostEvents as jt, DevframeServiceDescriptor as k, AgentToolProviderHandle as kt, McpRouteOptions as l, createStreamReader as lt, DevframeCapabilities as m, ImmutableObject as mt, DevframeDefinition as n, BufferedChunk as nt, DevframeSetupInfo as o, StreamReader as ot, ConnectionMetaWebsocket as p, ImmutableMap as pt, ScopedRpcFn as q, DevframeDeploymentKind as r, CreateStreamReaderOptions as rt, DevframeSseOptions as s, StreamSink as st, DevframeCliOptions as t, DevframeDiagnosticsLogger as tt, DevframeAuthHandler as u, createStreamSink as ut, RpcBroadcastOptions as v, SharedStateOptions as vt, RpcStreamingHost as w, AgentResourceContent as wt, RpcSharedStateHost as x, AgentHandle as xt, RpcFunctionsHost as y, SharedStatePatch as yt, DevframeScopedNodeContext as z };
+export { DevframeServicesHost as $, SharedStateEvents as A, AgentResource as At, DevframeSetupInfo as B, EventUnsubscribe as Bt, createStreamSink as C, DevframeAuthHandler as Ct, ImmutableObject as D, parseCliFlags as Dt, ImmutableMap as E, defineCliFlags as Et, DevframeDefinition as F, AgentToolProvider as Ft, McpRouteOptions as G, DevframeSnapshotRpcInputs as H, DevframeDeploymentKind as I, AgentToolProviderHandle as It, DevframeServiceId as J, DevframeServiceDefinition as K, DevframeDockDefaults as L, DevframeAgentHost as Lt, SharedStatePatch as M, AgentResourceInput as Mt, createSharedState as N, AgentTool as Nt, ImmutableSet as O, AgentHandle as Ot, DevframeCliOptions as P, AgentToolInput as Pt, DevframeServiceScopeOf as Q, DevframeDuplicationStrategy as R, DevframeAgentHostEvents as Rt, createStreamReader as S, DevframeDiagnosticsLogger as St, ImmutableArray as T, InferCliFlags as Tt, DevframeSseOptions as U, DevframeSnapshotRpcEntry as V, EventsMap as Vt, DevframeWsOptions as W, DevframeServiceMeta as X, DevframeServiceInput as Y, DevframeServiceOf as Z, CreateStreamSinkOptions as _, DevframeRpcServerFunctions as _t, DevframeConnectionConfigsRegistry as a, DevframeScopedStreamingHost as at, StreamSink as b, DevframeStorageScope as bt, RpcBroadcastOptions as c, DevframeSettingsStore as ct, RpcSharedStateHost as d, ScopedRpcFn as dt, DevframeServicesRegistry as et, RpcStreamingChannel as f, ScopedServerFunctions as ft, CreateStreamReaderOptions as g, DevframeRpcClientFunctions as gt, BufferedChunk as h, DevframeViewHost as ht, DevframeCapabilities as i, DevframeScopedNodeRpc as it, SharedStateOptions as j, AgentResourceContent as jt, SharedState as k, AgentManifest as kt, RpcFunctionsHost as l, ScopedBroadcastOptions as lt, RpcStreamingHost as m, SettingsForNamespace as mt, ConnectionMetaSse as n, DevframeServicesState as nt, DevframeNodeContext as o, DevframeSettings as ot, RpcStreamingChannelOptions as p, ScopedSharedStates as pt, DevframeServiceDescriptor as q, ConnectionMetaWebsocket as r, DevframeScopedNodeContext as rt, DevframeNodeRpcSession as s, DevframeSettingsRegistry as st, ConnectionMeta as t, DevframeServicesScopeRegistry as tt, RpcSharedStateGetOptions as u, ScopedClientFunctions as ut, StreamErrorPayload as v, DevframeRpcSharedStates as vt, Immutable as w, CliFlagsSchema as wt, StreamSinkEvents as x, DevframeDiagnosticsHost as xt, StreamReader as y, DevframeHost as yt, DevframeRpcOptions as z, EventEmitter as zt };