devframe 0.7.2 → 0.7.4

package/dist/{devframe-CnTVuGw9.d.mts → devframe-WHtcqYlZ.d.mts}

@@ -1,8 +1,9 @@
-import { _ as RpcFunctionDefinition } from "./types-CrzNxXKq.mjs";
+import { _ as RpcFunctionDefinition, v as RpcFunctionDefinitionAny } from "./types-CrzNxXKq.mjs";
 import { S as RpcFunctionsCollectorBase } from "./index-DgsLFhZg.mjs";
-import { t as DevframeNodeRpcSessionMeta } from "./ws-server-CceOy6He.mjs";
+import { t as DevframeNodeRpcSessionMeta } from "./ws-server-9-wn7MNQ.mjs";
 import { CAC } from "cac";
 import { GenericSchema, InferOutput } from "valibot";
+import { Peer } from "crossws";
 import { BirpcReturn } from "birpc";
 import { Diagnostic, DiagnosticDefinition, defineDiagnostics } from "nostics";
 //#region src/adapters/flags.d.ts
@@ -284,134 +285,185 @@ interface DevframeAgentHost {
   getResource: (id: string) => AgentResource | undefined;
 }
 //#endregion
-//#region src/types/diagnostics.d.ts
-/**
- * A diagnostics definition object built with `defineDiagnostics`. Typed as
- * `unknown` because each integration's definition has a distinct narrow shape
- * (e.g. specific code keys like `DF0001` / `MYP0001`), and TypeScript's mapped
- * types don't allow assigning a narrow-keyed result to a generically-keyed
- * one. The host stores them in a heterogeneous registry.
- */
-type DevframeDiagnosticsDefinition = ReturnType<typeof defineDiagnostics<any, any>>;
-/**
- * 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>;
+//#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]>; };
 /**
- * Options accepted by the host's `defineDiagnostics()` factory — mirrors
- * `nostics`'s shape but the host pre-wires its ANSI console reporter, so
- * plugins typically omit `reporters`.
+ * Serializable patch describing a single mutation to a `SharedState`.
+ * Structurally compatible with JSON-Patch and is safe to send over RPC.
  */
-interface DevframeDefineDiagnosticsOptions<Codes extends Record<string, DiagnosticDefinition>> {
-  docsBase?: string | ((code: keyof Codes) => string | undefined);
-  codes: Codes;
-  reporters?: ReadonlyArray<(d: Diagnostic, o?: any) => void>;
+interface SharedStatePatch {
+  op: 'add' | 'remove' | 'replace';
+  path: readonly (string | number)[];
+  value?: unknown;
 }
 /**
- * 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()
- * ```
+ * State host that is immutable by default with explicit mutate.
  */
-interface DevframeDiagnosticsHost {
+interface SharedState<T> {
   /**
-   * 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.
+   * Get the current state. Immutable.
    */
-  readonly logger: DevframeDiagnosticsLogger;
+  value: () => Immutable<T>;
   /**
-   * 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.
+   * Subscribe to state changes.
    */
-  register: (definitions: Record<string, unknown>) => void;
+  on: EventEmitter<SharedStateEvents<T>>['on'];
   /**
-   * Build a typed diagnostics object with the host's ANSI console reporter
-   * pre-wired. Mirrors `nostics`'s `defineDiagnostics` so integrations don't
-   * need to take a direct dependency on `nostics`.
+   * Mutate the state.
    */
-  defineDiagnostics: <const Codes extends Record<string, DiagnosticDefinition>>(options: DevframeDefineDiagnosticsOptions<Codes>) => ReturnType<typeof defineDiagnostics<Codes, any>>;
+  mutate: (fn: (state: T) => void, syncId?: string) => void;
+  /**
+   * Apply patches to the state.
+   */
+  patch: (patches: SharedStatePatch[], syncId?: string) => void;
+  /**
+   * Sync IDs that have been applied to the state.
+   */
+  syncIds: Set<string>;
 }
-//#endregion
-//#region src/types/host.d.ts
-interface DevframeHost {
+interface SharedStateEvents<T> {
+  updated: (fullState: T, patches: SharedStatePatch[] | undefined, syncId: string) => void;
+}
+interface SharedStateOptions<T> {
   /**
-   * Serve a static directory at the given URL base. Called by
-   * `DevframeViewHost.hostStatic`. Implementations map this to whatever
-   * the underlying runtime expects (Vite middleware, h3 handler, no-op
-   * for build snapshots).
+   * Initial state.
    */
-  mountStatic: (base: string, distDir: string) => void | Promise<void>;
+  initialValue: T;
   /**
-   * Serve the host's connection meta (`__connection.json`) at the given URL
-   * base, so a devframe SPA mounted there can discover the RPC/WS endpoint
-   * via `connectDevframe()`'s relative `./__connection.json` fetch.
-   *
-   * Called by `mountDevframe` for each mounted devframe (alongside
-   * `mountStatic`). Without it, an embedded SPA can only discover the
-   * endpoint by inheriting it from a same-origin parent window — which fails
-   * for cross-origin or sandboxed iframes. Implementations serve the same
-   * meta they expose at the hub's own base.
+   * Enable patches.
    *
-   * Optional in the type, but a host that mounts a devframe with a servable
-   * `distDir` yet omits this hook triggers a `DF8106` diagnostic, since the
-   * SPA's `./__connection.json` fetch would otherwise fall through and break
-   * silently. A static-snapshot host that bakes the meta into its served files
-   * can implement it as a no-op to acknowledge this intentionally.
+   * @default false
    */
-  mountConnectionMeta?: (base: string) => void | Promise<void>;
+  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;
+}
+/**
+ * Single buffered chunk in the server-side ring buffer.
+ *
+ * Sequence numbers start at 1 and increment per write. Subscribers track
+ * `lastSeenSeq` and ask for `afterSeq` on resubscribe so the server can
+ * replay any chunks the client missed during a brief disconnect.
+ */
+interface BufferedChunk<T> {
+  seq: number;
+  chunk: T;
+}
+interface StreamSinkEvents<T> {
+  /** Fired for each `write()`. The RPC layer subscribes and broadcasts. */
+  chunk: (seq: number, chunk: T) => void;
+  /** Terminal — fired exactly once per sink lifetime. */
+  end: (error?: StreamErrorPayload) => void;
+}
+interface CreateStreamSinkOptions {
+  id?: string;
   /**
-   * Return the public origin the host is reachable at, e.g.
-   * `http://localhost:5173`. Used by the dock host to enrich remote
-   * iframe URLs with a full `origin`. Called only when a dock needs an
-   * absolute URL; hosts that never serve remote docks can return any
-   * reasonable value.
+   * Size of the per-stream ring buffer kept for replay-on-resubscribe.
+   * `0` (default) disables replay.
    */
-  resolveOrigin: () => string;
+  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;
   /**
-   * Resolve a directory the host owns for persisted devframe state.
-   * Each host picks its own app-name namespace so storage doesn't
-   * collide between, say, the Vite host (`.vite/devframe`) and a
-   * standalone CLI host (`.<appName>/devframe`).
+   * Aborts when the consumer cancels (server-side) or when the transport
+   * loses every subscriber. Producers should poll `signal.aborted` and exit
+   * cleanly.
+   */
+  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.
    *
-   *   - `workspace` — per-project state (settings, caches). Typically
-   *     under `${workspaceRoot}/node_modules/.<appName>/devframe/`.
-   *   - `global`    — per-user state (auth tokens, machine-wide
-   *     preferences). Typically under
-   *     `${homedir()}/.<appName>/devframe/`.
+   * @internal
+   */
+  readonly events: EventEmitter<StreamSinkEvents<T>>;
+  /**
+   * Internal — replay buffer. RPC layer reads on (re)subscribe to feed
+   * missed chunks before going live.
    *
-   * Implementations should ensure the directory exists or be safe to
-   * pass to a downstream `createStorage(...)` call that creates it
-   * lazily.
+   * @internal
    */
-  getStorageDir: (scope: 'workspace' | 'global') => string;
+  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/rpc-augments.d.ts
 /**
@@ -588,543 +640,555 @@ interface DevframeRpcServerFunctions {
  */
 interface DevframeRpcSharedStates {}
 //#endregion
-//#region src/types/views.d.ts
-interface DevframeViewHost {
+//#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> & {
   /**
-   * @internal
+   * Invoke a locally registered server RPC function directly.
+   *
+   * This bypasses transport and is useful for server-side cross-function calls.
    */
-  buildStaticDirs: {
-    baseUrl: string;
-    distDir: string;
-  }[];
+  invokeLocal: <T extends keyof DevframeRpcServerFunctions, Args extends Parameters<DevframeRpcServerFunctions[T]>>(method: T, ...args: Args) => Promise<Awaited<ReturnType<DevframeRpcServerFunctions[T]>>>;
   /**
-   * 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
+   * Broadcast a message to all connected clients
    */
-  hostStatic: (baseUrl: string, distDir: string) => void;
-}
-//#endregion
-//#region src/types/scope.d.ts
-type AnyRpcFn = (...args: any[]) => any;
-/**
- * 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>>;
+  broadcast: <T extends keyof DevframeRpcClientFunctions, Args extends Parameters<DevframeRpcClientFunctions[T]>>(options: RpcBroadcastOptions<T, Args>) => Promise<void>;
   /**
-   * Subscribe to settings changes. Resolves to an unsubscribe function.
-   * Fires on every local or remote mutation with the full snapshot.
+   * Get the current RPC client
+   *
+   * Available in RPC functions to get the current RPC client
    */
-  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;
+  getCurrentRpcSession: () => DevframeNodeRpcSession | undefined;
+  /**
+   * The shared state host
+   */
+  sharedState: RpcSharedStateHost;
+  /**
+   * The streaming channel host. Provides per-channel `start()` /
+   * `pipeFrom()` producers; clients consume via `rpc.streaming.subscribe()`.
+   *
+   * @see RpcStreamingHost
+   */
+  streaming: RpcStreamingHost;
+};
+interface RpcSharedStateGetOptions<T> {
+  sharedState?: SharedState<T>;
+  initialValue?: T;
 }
-/**
- * Node-side streaming host scoped to a namespace. Channel names are
- * auto-prefixed with `<namespace>:`.
- */
-interface DevframeScopedStreamingHost {
+interface RpcSharedStateHost {
+  get: <T extends object = any>(key: string, options?: RpcSharedStateGetOptions<T>) => Promise<SharedState<T>>;
+  keys: () => string[];
   /**
-   * Register a streaming channel. The bare `name` is auto-prefixed with
-   * the scope namespace (`<namespace>:<name>`); pass an already-qualified
-   * name (containing `:`) to opt out.
+   * 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.
    */
-  create: <T = unknown>(name: string, opts?: RpcStreamingChannelOptions) => RpcStreamingChannel<T>;
+  onKeyAdded: (fn: (key: string) => void) => () => void;
 }
 /**
- * The scoped node RPC surface exposed on `ctx.scope('my-plugin').rpc`.
- * IDs and keys you pass are auto-namespaced with `my-plugin:`.
+ * Options for `RpcStreamingHost.create()`.
  */
-interface DevframeScopedNodeRpc<NS extends string = string> {
-  /** The namespace this surface is scoped to. */
-  readonly namespace: NS;
+interface RpcStreamingChannelOptions {
   /**
-   * Register a server RPC function. The definition's `name` must be bare
-   * (no `:`); it is stored as `<namespace>:<name>`. Throws `DF0034` if an
-   * already-namespaced name is passed.
+   * 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.
    */
-  register: (fn: RpcFunctionDefinition<string, any, any, any, any, any, DevframeNodeContext>, force?: boolean) => void;
+  replayWindow?: number;
   /**
-   * Update a previously registered server RPC function. Same naming rules
-   * as {@link DevframeScopedNodeRpc.register}.
+   * 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.
    */
-  update: (fn: RpcFunctionDefinition<string, any, any, any, any, any, DevframeNodeContext>, force?: boolean) => void;
+  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;
   /**
-   * Invoke a locally registered server RPC function. Bare names are
-   * resolved within this namespace; pass a fully-qualified name
-   * (containing `:`) to call another scope's function.
+   * 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.
    */
-  call: {
-    <T extends keyof ScopedServerFunctions<NS> & string>(method: T, ...args: Parameters<Extract<ScopedServerFunctions<NS>[T], AnyRpcFn>>): Promise<Awaited<ReturnType<Extract<ScopedServerFunctions<NS>[T], AnyRpcFn>>>>;
-    <T extends keyof DevframeRpcServerFunctions & string>(method: T, ...args: Parameters<Extract<DevframeRpcServerFunctions[T], AnyRpcFn>>): Promise<Awaited<ReturnType<Extract<DevframeRpcServerFunctions[T], AnyRpcFn>>>>;
-    (method: string, ...args: any[]): Promise<any>;
-  };
+  start: (opts?: {
+    id?: string;
+  }) => StreamSink<T>;
   /**
-   * Broadcast a client RPC event to every connected client. Bare method
-   * names are resolved within this namespace.
+   * 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.
    */
-  broadcast: {
-    <T extends keyof ScopedClientFunctions<NS> & string>(options: ScopedBroadcastOptions<T, Parameters<Extract<ScopedClientFunctions<NS>[T], AnyRpcFn>>>): Promise<void>;
-    (options: ScopedBroadcastOptions<string, any[]>): Promise<void>;
-  };
+  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[];
   /**
-   * Resolve a namespaced shared state. Bare keys are resolved within this
-   * namespace; pass a fully-qualified key (containing `:`) to opt out.
+   * Open an inbound stream — the server side of a client-to-server
+   * upload. Allocates an id, returns a `StreamReader<T>` that fills as
+   * the client writes chunks. Typical pattern is to call this from an
+   * action handler, kick off background processing, and return the id
+   * so the caller can start uploading:
+   *
+   * ```ts
+   * handler: async () => {
+   *   const reader = channel.openInbound()
+   *   ;(async () => {
+   *     for await (const chunk of reader) processChunk(chunk)
+   *   })()
+   *   return { uploadId: reader.id }
+   * }
+   * ```
+   *
+   * Calling `reader.cancel()` on the server sends an `upload-cancel` to
+   * the uploading client, which aborts its sink.
    */
-  sharedState: {
-    <T extends keyof ScopedSharedStates<NS> & string>(key: T, options?: RpcSharedStateGetOptions<ScopedSharedStates<NS>[T]>): Promise<SharedState<ScopedSharedStates<NS>[T]>>;
-    <T extends Record<string, any> = Record<string, any>>(key: string, options?: RpcSharedStateGetOptions<T>): Promise<SharedState<T>>;
-  };
-  /** Streaming host scoped to this namespace. */
-  streaming: DevframeScopedStreamingHost;
-  /** Pass-through to the current RPC session, when called inside a handler. */
-  getCurrentRpcSession: () => DevframeNodeRpcSession | undefined;
+  openInbound: (opts?: {
+    id?: string;
+  }) => StreamReader<T>;
 }
 /**
- * A namespace-scoped view of {@link DevframeNodeContext}. Returned by
- * `ctx.scope('my-plugin')`. Re-exposes the unscoped surfaces (`views`,
- * `diagnostics`, `agent`, …), replaces `rpc` with the auto-namespaced
- * {@link DevframeScopedNodeRpc}, and adds a top-level `settings` store.
+ * 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 DevframeScopedNodeContext<NS extends string = string, Settings extends Record<string, any> = Record<string, any>> {
-  /** The namespace this context is scoped to. */
-  readonly namespace: NS;
-  /** The underlying unscoped context. */
-  readonly base: DevframeNodeContext;
-  readonly workspaceRoot: string;
-  readonly cwd: string;
-  readonly mode: 'dev' | 'build';
-  host: DevframeHost;
-  rpc: DevframeScopedNodeRpc<NS>;
-  /** Persisted settings for this namespace (`global` + `project`). */
-  settings: DevframeSettings<Settings>;
-  views: DevframeViewHost;
-  diagnostics: DevframeDiagnosticsHost;
-  agent: DevframeAgentHost;
+interface RpcStreamingHost {
   /**
-   * Return a new scoped context, replacing the current scope. Pass `null`
-   * or `''` to un-scope and get the base context.
+   * 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.
    */
-  scope: DevframeNodeContext['scope'];
+  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 `startHttpAndWs` automatically.
+   *
+   * @internal
+   */
+  _onSessionDisconnected: (meta: DevframeNodeRpcSessionMeta) => void;
 }
 //#endregion
-//#region src/types/utils.d.ts
-type Thenable<T> = T | Promise<T>;
-type EntriesToObject<T extends readonly [string, any][]> = { [K in T[number] as K[0]]: K[1]; };
-type PartialWithoutId<T extends {
-  id: string;
-}> = Partial<Omit<T, 'id'>> & {
-  id: string;
-};
-//#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/types/diagnostics.d.ts
 /**
- * Serializable patch describing a single mutation to a `SharedState`.
- * Structurally compatible with JSON-Patch and is safe to send over RPC.
+ * A diagnostics definition object built with `defineDiagnostics`. Typed as
+ * `unknown` because each integration's definition has a distinct narrow shape
+ * (e.g. specific code keys like `DF0001` / `MYP0001`), and TypeScript's mapped
+ * types don't allow assigning a narrow-keyed result to a generically-keyed
+ * one. The host stores them in a heterogeneous registry.
  */
-interface SharedStatePatch {
-  op: 'add' | 'remove' | 'replace';
-  path: readonly (string | number)[];
-  value?: unknown;
+type DevframeDiagnosticsDefinition = ReturnType<typeof defineDiagnostics<any, any>>;
+/**
+ * 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>;
+/**
+ * Options accepted by the host's `defineDiagnostics()` factory — mirrors
+ * `nostics`'s shape but the host pre-wires its ANSI console reporter, so
+ * plugins typically omit `reporters`.
+ */
+interface DevframeDefineDiagnosticsOptions<Codes extends Record<string, DiagnosticDefinition>> {
+  docsBase?: string | ((code: keyof Codes) => string | undefined);
+  codes: Codes;
+  reporters?: ReadonlyArray<(d: Diagnostic, o?: any) => void>;
 }
 /**
- * State host that is immutable by default with explicit mutate.
+ * 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 SharedState<T> {
+interface DevframeDiagnosticsHost {
   /**
-   * Get the current state. Immutable.
+   * 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.
    */
-  value: () => Immutable<T>;
+  readonly logger: DevframeDiagnosticsLogger;
   /**
-   * Subscribe to state changes.
+   * 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.
    */
-  on: EventEmitter<SharedStateEvents<T>>['on'];
+  register: (definitions: Record<string, unknown>) => void;
   /**
-   * Mutate the state.
+   * Build a typed diagnostics object with the host's ANSI console reporter
+   * pre-wired. Mirrors `nostics`'s `defineDiagnostics` so integrations don't
+   * need to take a direct dependency on `nostics`.
    */
-  mutate: (fn: (state: T) => void, syncId?: string) => void;
+  defineDiagnostics: <const Codes extends Record<string, DiagnosticDefinition>>(options: DevframeDefineDiagnosticsOptions<Codes>) => ReturnType<typeof defineDiagnostics<Codes, any>>;
+}
+//#endregion
+//#region src/types/host.d.ts
+interface DevframeHost {
   /**
-   * Apply patches to the state.
+   * Serve a static directory at the given URL base. Called by
+   * `DevframeViewHost.hostStatic`. Implementations map this to whatever
+   * the underlying runtime expects (Vite middleware, h3 handler, no-op
+   * for build snapshots).
    */
-  patch: (patches: SharedStatePatch[], syncId?: string) => void;
+  mountStatic: (base: string, distDir: string) => void | Promise<void>;
   /**
-   * Sync IDs that have been applied to the state.
+   * Serve the host's connection meta (`__connection.json`) at the given URL
+   * base, so a devframe SPA mounted there can discover the RPC/WS endpoint
+   * via `connectDevframe()`'s relative `./__connection.json` fetch.
+   *
+   * Called by `mountDevframe` for each mounted devframe (alongside
+   * `mountStatic`). Without it, an embedded SPA can only discover the
+   * endpoint by inheriting it from a same-origin parent window — which fails
+   * for cross-origin or sandboxed iframes. Implementations serve the same
+   * meta they expose at the hub's own base.
+   *
+   * Optional in the type, but a host that mounts a devframe with a servable
+   * `distDir` yet omits this hook triggers a `DF8106` diagnostic, since the
+   * SPA's `./__connection.json` fetch would otherwise fall through and break
+   * silently. A static-snapshot host that bakes the meta into its served files
+   * can implement it as a no-op to acknowledge this intentionally.
    */
-  syncIds: Set<string>;
-}
-interface SharedStateEvents<T> {
-  updated: (fullState: T, patches: SharedStatePatch[] | undefined, syncId: string) => void;
-}
-interface SharedStateOptions<T> {
+  mountConnectionMeta?: (base: string) => void | Promise<void>;
   /**
-   * Initial state.
+   * Return the public origin the host is reachable at, e.g.
+   * `http://localhost:5173`. Used by the dock host to enrich remote
+   * iframe URLs with a full `origin`. Called only when a dock needs an
+   * absolute URL; hosts that never serve remote docks can return any
+   * reasonable value.
    */
-  initialValue: T;
+  resolveOrigin: () => string;
   /**
-   * Enable patches.
+   * Resolve a directory the host owns for persisted devframe state.
+   * Each host picks its own app-name namespace so storage doesn't
+   * collide between, say, the Vite host (`.vite/devframe`) and a
+   * standalone CLI host (`.<appName>/devframe`).
    *
-   * @default false
-   */
-  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;
-}
-/**
- * Single buffered chunk in the server-side ring buffer.
- *
- * Sequence numbers start at 1 and increment per write. Subscribers track
- * `lastSeenSeq` and ask for `afterSeq` on resubscribe so the server can
- * replay any chunks the client missed during a brief disconnect.
- */
-interface BufferedChunk<T> {
-  seq: number;
-  chunk: T;
-}
-interface StreamSinkEvents<T> {
-  /** Fired for each `write()`. The RPC layer subscribes and broadcasts. */
-  chunk: (seq: number, chunk: T) => void;
-  /** Terminal — fired exactly once per sink lifetime. */
-  end: (error?: StreamErrorPayload) => void;
-}
-interface CreateStreamSinkOptions {
-  id?: string;
-  /**
-   * Size of the per-stream ring buffer kept for replay-on-resubscribe.
-   * `0` (default) disables replay.
+   *   - `workspace` — state shared with the whole team through version
+   *     control (saved queries, shared presets). Conventionally
+   *     `${workspaceRoot}/.devframe/`; hosts must place it somewhere
+   *     committable.
+   *   - `project`   — per-checkout private state (caches, personal
+   *     settings). Typically under
+   *     `${cwd}/node_modules/.<appName>/devframe/`, which version
+   *     control ignores.
+   *   - `global`    — per-user state (auth tokens, machine-wide
+   *     preferences). Typically under
+   *     `${homedir()}/.<appName>/devframe/`.
+   *
+   * Implementations should ensure the directory exists or be safe to
+   * pass to a downstream `createStorage(...)` call that creates it
+   * lazily.
    */
-  replayWindow?: number;
+  getStorageDir: (scope: DevframeStorageScope) => string;
 }
 /**
- * Server-side producer handle. Two equivalent surfaces share one piece of
- * state: the imperative `write/error/close` triple, and a `WritableStream<T>`
- * for `pipeTo`-style consumption.
+ * Storage placement classes for {@link DevframeHost.getStorageDir}:
+ * `workspace` is committable and team-shared, `project` is per-checkout
+ * private, `global` is per-user.
  */
-interface StreamSink<T> {
-  /** Stable id used by clients to subscribe. */
-  readonly id: string;
-  /**
-   * Aborts when the consumer cancels (server-side) or when the transport
-   * loses every subscriber. Producers should poll `signal.aborted` and exit
-   * cleanly.
-   */
-  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>;
+type DevframeStorageScope = 'workspace' | 'project' | 'global';
+//#endregion
+//#region src/types/views.d.ts
+interface DevframeViewHost {
   /**
-   * 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>>;
+  buildStaticDirs: {
+    baseUrl: string;
+    distDir: string;
+  }[];
   /**
-   * Internal — replay buffer. RPC layer reads on (re)subscribe to feed
-   * missed chunks before going live.
-   *
-   * @internal
+   * 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
    */
-  readonly buffer: ReadonlyArray<BufferedChunk<T>>;
+  hostStatic: (baseUrl: string, distDir: string) => void;
 }
-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;
+//#endregion
+//#region src/types/scope.d.ts
+type AnyRpcFn = (...args: any[]) => any;
+/**
+ * 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>>;
   /**
-   * 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.
+   * Subscribe to settings changes. Resolves to an unsubscribe function.
+   * Fires on every local or remote mutation with the full snapshot.
    */
-  onOverflow?: (dropped: number) => void;
-  /** Called when the consumer cancels — the RPC layer sends `:cancel` upstream. */
-  onCancel?: () => void;
+  onChange: (fn: (value: Readonly<T>) => void) => Promise<() => 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.
+ * 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 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;
+interface DevframeSettings<T extends Record<string, any> = Record<string, any>> {
+  global: DevframeSettingsStore<T>;
+  project: DevframeSettingsStore<T>;
 }
 /**
- * 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.
+ * 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.
  */
-declare function createStreamSink<T>(options?: CreateStreamSinkOptions): StreamSink<T>;
+type ScopedSharedStates<NS extends string> = { [K in keyof DevframeRpcSharedStates as K extends `${NS}:${infer R}` ? R : never]: DevframeRpcSharedStates[K]; };
 /**
- * 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`.
+ * Broadcast options for a scoped client method (bare name).
  */
-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[]> {
+interface ScopedBroadcastOptions<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> & {
+/**
+ * Node-side streaming host scoped to a namespace. Channel names are
+ * auto-prefixed with `<namespace>:`.
+ */
+interface DevframeScopedStreamingHost {
   /**
-   * Invoke a locally registered server RPC function directly.
-   *
-   * This bypasses transport and is useful for server-side cross-function calls.
+   * Register a streaming channel. The bare `name` is auto-prefixed with
+   * the scope namespace (`<namespace>:<name>`); pass an already-qualified
+   * name (containing `:`) to opt out.
    */
-  invokeLocal: <T extends keyof DevframeRpcServerFunctions, Args extends Parameters<DevframeRpcServerFunctions[T]>>(method: T, ...args: Args) => Promise<Awaited<ReturnType<DevframeRpcServerFunctions[T]>>>;
+  create: <T = unknown>(name: string, opts?: RpcStreamingChannelOptions) => RpcStreamingChannel<T>;
+}
+/**
+ * The scoped node RPC surface exposed on `ctx.scope('my-plugin').rpc`.
+ * IDs and keys you pass are auto-namespaced with `my-plugin:`.
+ */
+interface DevframeScopedNodeRpc<NS extends string = string> {
+  /** The namespace this surface is scoped to. */
+  readonly namespace: NS;
   /**
-   * Broadcast a message to all connected clients
+   * Register a server RPC function. The definition's `name` must be bare
+   * (no `:`); it is stored as `<namespace>:<name>`. Throws `DF0034` if an
+   * already-namespaced name is passed.
    */
-  broadcast: <T extends keyof DevframeRpcClientFunctions, Args extends Parameters<DevframeRpcClientFunctions[T]>>(options: RpcBroadcastOptions<T, Args>) => Promise<void>;
+  register: (fn: RpcFunctionDefinition<string, any, any, any, any, any, DevframeNodeContext>, force?: boolean) => void;
   /**
-   * Get the current RPC client
-   *
-   * Available in RPC functions to get the current RPC client
+   * Update a previously registered server RPC function. Same naming rules
+   * as {@link DevframeScopedNodeRpc.register}.
    */
-  getCurrentRpcSession: () => DevframeNodeRpcSession | undefined;
+  update: (fn: RpcFunctionDefinition<string, any, any, any, any, any, DevframeNodeContext>, force?: boolean) => void;
   /**
-   * The shared state host
+   * Invoke a locally registered server RPC function. Bare names are
+   * resolved within this namespace; pass a fully-qualified name
+   * (containing `:`) to call another scope's function.
    */
-  sharedState: RpcSharedStateHost;
+  call: {
+    <T extends keyof ScopedServerFunctions<NS> & string>(method: T, ...args: Parameters<Extract<ScopedServerFunctions<NS>[T], AnyRpcFn>>): Promise<Awaited<ReturnType<Extract<ScopedServerFunctions<NS>[T], AnyRpcFn>>>>;
+    <T extends keyof DevframeRpcServerFunctions & string>(method: T, ...args: Parameters<Extract<DevframeRpcServerFunctions[T], AnyRpcFn>>): Promise<Awaited<ReturnType<Extract<DevframeRpcServerFunctions[T], AnyRpcFn>>>>;
+    (method: string, ...args: any[]): Promise<any>;
+  };
   /**
-   * The streaming channel host. Provides per-channel `start()` /
-   * `pipeFrom()` producers; clients consume via `rpc.streaming.subscribe()`.
-   *
-   * @see RpcStreamingHost
+   * Broadcast a client RPC event to every connected client. Bare method
+   * names are resolved within this namespace.
    */
-  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[];
+  broadcast: {
+    <T extends keyof ScopedClientFunctions<NS> & string>(options: ScopedBroadcastOptions<T, Parameters<Extract<ScopedClientFunctions<NS>[T], AnyRpcFn>>>): Promise<void>;
+    (options: ScopedBroadcastOptions<string, any[]>): Promise<void>;
+  };
   /**
-   * 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.
+   * Resolve a namespaced shared state. Bare keys are resolved within this
+   * namespace; pass a fully-qualified key (containing `:`) to opt out.
    */
-  onKeyAdded: (fn: (key: string) => void) => () => void;
+  sharedState: {
+    <T extends keyof ScopedSharedStates<NS> & string>(key: T, options?: RpcSharedStateGetOptions<ScopedSharedStates<NS>[T]>): Promise<SharedState<ScopedSharedStates<NS>[T]>>;
+    <T extends Record<string, any> = Record<string, any>>(key: string, options?: RpcSharedStateGetOptions<T>): Promise<SharedState<T>>;
+  };
+  /** Streaming host scoped to this namespace. */
+  streaming: DevframeScopedStreamingHost;
+  /** Pass-through to the current RPC session, when called inside a handler. */
+  getCurrentRpcSession: () => DevframeNodeRpcSession | undefined;
 }
 /**
- * Options for `RpcStreamingHost.create()`.
+ * A namespace-scoped view of {@link DevframeNodeContext}. Returned by
+ * `ctx.scope('my-plugin')`. Re-exposes the unscoped surfaces (`views`,
+ * `diagnostics`, `agent`, …), replaces `rpc` with the auto-namespaced
+ * {@link DevframeScopedNodeRpc}, and adds a top-level `settings` store.
  */
-interface RpcStreamingChannelOptions {
-  /**
-   * Size of the per-stream ring buffer kept on the server for
-   * replay-on-resubscribe. `0` (default) disables replay; on reconnect
-   * the consumer only sees chunks that arrive after subscribing.
-   *
-   * The buffer is per stream id, not per channel — each `channel.start()`
-   * gets its own.
-   */
-  replayWindow?: number;
+interface DevframeScopedNodeContext<NS extends string = string, Settings extends Record<string, any> = Record<string, any>> {
+  /** The namespace this context is scoped to. */
+  readonly namespace: NS;
+  /** The underlying unscoped context. */
+  readonly base: DevframeNodeContext;
+  readonly workspaceRoot: string;
+  readonly cwd: string;
+  readonly mode: 'dev' | 'build';
+  host: DevframeHost;
+  rpc: DevframeScopedNodeRpc<NS>;
+  /** Persisted settings for this namespace (`global` + `project`). */
+  settings: DevframeSettings<Settings>;
+  views: DevframeViewHost;
+  diagnostics: DevframeDiagnosticsHost;
+  agent: DevframeAgentHost;
   /**
-   * 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.
+   * Return a new scoped context, replacing the current scope. Pass `null`
+   * or `''` to un-scope and get the base context.
    */
-  closedStreamRetention?: number;
+  scope: DevframeNodeContext['scope'];
 }
+//#endregion
+//#region src/types/services.d.ts
 /**
- * Channel handle returned by `ctx.rpc.streaming.create(name, opts)`. A
- * channel owns a wire namespace; calling `start()` produces individual
- * streams keyed by id.
+ * Cross-plugin services — a typed, namespaced registry on the shared node
+ * context through which one integration exposes a capability and others
+ * consume it without a hard package dependency.
  *
- * @see {@link https://devfra.me/guide/streaming Streaming guide}
+ * A provider ships a *types-only* augmentation of {@link DevframeServicesRegistry}
+ * (so consumers get full typing from `import type`), then provides the
+ * implementation at setup time:
+ *
+ * ```ts
+ * // provider (e.g. the data-inspector plugin)
+ * declare module 'devframe' {
+ *   interface DevframeServicesRegistry {
+ *     'devframes:plugin:data-inspector:sources': DataSourcesService
+ *   }
+ * }
+ * ctx.services.provide('devframes:plugin:data-inspector:sources', host)
+ *
+ * // consumer (another plugin) — no runtime dependency on the provider
+ * ctx.services.whenAvailable('devframes:plugin:data-inspector:sources', (sources) => {
+ *   sources.register({ id: 'my-plugin:state', title: 'My state', data: () => state })
+ * })
+ * ```
+ *
+ * Service ids follow the same namespacing rule as RPC functions: prefix with
+ * the providing plugin's id.
  */
-interface RpcStreamingChannel<T = unknown> {
-  /** Channel name as registered with `ctx.rpc.streaming.create()`. */
-  readonly name: string;
-  /**
-   * 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.
-   */
-  start: (opts?: {
-    id?: string;
-  }) => StreamSink<T>;
-  /**
-   * 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.
-   */
-  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[];
-  /**
-   * Open an inbound stream — the server side of a client-to-server
-   * upload. Allocates an id, returns a `StreamReader<T>` that fills as
-   * the client writes chunks. Typical pattern is to call this from an
-   * action handler, kick off background processing, and return the id
-   * so the caller can start uploading:
-   *
-   * ```ts
-   * handler: async () => {
-   *   const reader = channel.openInbound()
-   *   ;(async () => {
-   *     for await (const chunk of reader) processChunk(chunk)
-   *   })()
-   *   return { uploadId: reader.id }
-   * }
-   * ```
-   *
-   * Calling `reader.cancel()` on the server sends an `upload-cancel` to
-   * the uploading client, which aborts its sink.
-   */
-  openInbound: (opts?: {
-    id?: string;
-  }) => StreamReader<T>;
-}
 /**
- * Server-side streaming host. Lives on `ctx.rpc.streaming` alongside
- * `ctx.rpc.sharedState`. Each named channel owns its own stream registry
- * and wire namespace.
+ * Augmentation point mapping service ids to their implementation types.
+ * Providers extend this via `declare module 'devframe'`.
  */
-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 `startHttpAndWs` automatically.
-   *
-   * @internal
-   */
-  _onSessionDisconnected: (meta: DevframeNodeRpcSessionMeta) => void;
+interface DevframeServicesRegistry {}
+/**
+ * A known (augmented) service id, or any namespaced string for services
+ * without a published type augmentation.
+ */
+type DevframeServiceId = keyof DevframeServicesRegistry | (string & {});
+/** Resolved service type for an id: augmented type, or `unknown`. */
+type DevframeServiceOf<ID> = ID extends keyof DevframeServicesRegistry ? DevframeServicesRegistry[ID] : unknown;
+interface DevframeServicesHost {
+  /**
+   * Publish a service under a namespaced id. Throws `DF0037` when the id is
+   * already provided (revoke first to replace). Returns a revoke function.
+   */
+  provide: <ID extends DevframeServiceId>(id: ID, service: DevframeServiceOf<ID>) => () => void;
+  /** The service currently provided under `id`, or `undefined`. */
+  get: <ID extends DevframeServiceId>(id: ID) => DevframeServiceOf<ID> | undefined;
+  has: (id: DevframeServiceId) => boolean;
+  /**
+   * Run `callback` with the service as soon as it is available — immediately
+   * when already provided, otherwise on `provide`. Survives provider/consumer
+   * setup-order differences. The callback also re-fires if the service is
+   * revoked and provided again. Returns an unsubscribe function.
+   */
+  whenAvailable: <ID extends DevframeServiceId>(id: ID, callback: (service: DevframeServiceOf<ID>) => void) => () => void;
+  /** Ids of every currently-provided service. */
+  keys: () => string[];
 }
 //#endregion
 //#region src/types/context.d.ts
@@ -1175,6 +1239,15 @@ interface DevframeNodeContext {
    * @experimental
    */
   agent: DevframeAgentHost;
+  /**
+   * 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.
+   */
+  services: DevframeServicesHost;
   /**
    * Create a namespace-scoped view of this context. The returned
    * `ctx.scope('my-plugin')` auto-namespaces every RPC id, shared-state
@@ -1252,6 +1325,71 @@ interface ConnectionMeta {
    * endpoint rather than resolving the path against its own mount.
    */
   baseUrl?: string;
+  /**
+   * A pre-issued bearer token embedded in the meta so a client trusts the
+   * server on connect without any prompt or `localStorage` lookup. Only a
+   * **hub** serving a **per-frame** connection meta populates this — it
+   * authenticates once at the top level and bakes the resulting token into
+   * the meta each plugin iframe fetches, so a cross-origin frame (which
+   * cannot read the hub's `localStorage`) is still pre-authorized. The
+   * standalone `__connection.json` never carries a token.
+   *
+   * > [!WARNING]
+   * > A token in a fetchable JSON is only as protected as the URL serving
+   * > it. Emit it exclusively from hub-controlled, per-frame meta — never
+   * > from a publicly reachable static `__connection.json`.
+   */
+  authToken?: string;
+}
+//#endregion
+//#region src/types/utils.d.ts
+type Thenable<T> = T | Promise<T>;
+type EntriesToObject<T extends readonly [string, any][]> = { [K in T[number] as K[0]]: K[1]; };
+type PartialWithoutId<T extends {
+  id: string;
+}> = Partial<Omit<T, 'id'>> & {
+  id: 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.
+ *
+ * `startHttpAndWs` accepts one of these directly via its `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 {
+  /**
+   * `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).
+   */
+  rpcFunctions: RpcFunctionDefinitionAny[];
+  /**
+   * Resolver gate: whether `methodName` is callable given `session`'s
+   * current trust state. Defaults to allowing any `anonymous:`-prefixed
+   * method (see `isAnonymousRpcMethod`) plus anything once the session is
+   * trusted.
+   */
+  authorize: (methodName: string, session: DevframeNodeRpcSession) => boolean;
+  /**
+   * Connect-time trust: reads a bearer token off the peer's upgrade request
+   * (an `Authorization: Bearer <token>` header, or a static/pre-shared
+   * token from `clientAuthTokens`) and, when valid, marks the session
+   * trusted immediately — before the client's own handshake call.
+   */
+  onConnect: (peer: Peer, session: DevframeNodeRpcSession) => void;
+  /**
+   * 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.
+   */
+  printBanner: () => void;
 }
 //#endregion
 //#region src/types/devframe.d.ts
@@ -1356,14 +1494,27 @@ interface DevframeCliOptions {
    */
   open?: boolean | string;
   /**
-   * Skip the RPC trust handshake. Set to `false` for trusted
-   * single-user localhost tools. Default `true`.
+   * Authentication for the standalone dev server.
+   *
+   *   - `undefined` / `true` — the standalone adapters (`cli` / `spa` /
+   *     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 `startHttpAndWs`.
+   *
+   * Hosted adapters (`vite`, `embedded`) ignore this and defer to the host's
+   * auth; `@vitejs/devtools` honors the equivalent `devtools.clientAuth`.
    *
-   * Forwarded to `startHttpAndWs` as a no-op placeholder until devframe
-   * ships its own auth layer; `@vitejs/devtools` honors the equivalent
-   * `devtools.clientAuth` today.
+   * @default true
    */
-  auth?: boolean;
+  auth?: boolean | DevframeAuthHandler;
   /**
    * Expose a route-based MCP server alongside the dev server, speaking the
    * MCP Streamable-HTTP transport at `/__mcp` (relative to the base path).
@@ -1538,4 +1689,4 @@ interface DevframeDefinition {
 }
 declare function defineDevframe(d: DevframeDefinition): DevframeDefinition;
 //#endregion
-export { ScopedBroadcastOptions as $, StreamSink as A, SharedStateEvents as B, RpcStreamingChannelOptions as C, EventUnsubscribe as Ct, CreateStreamSinkOptions as D, defineCliFlags as Dt, CreateStreamReaderOptions as E, InferCliFlags as Et, ImmutableArray as F, PartialWithoutId as G, SharedStatePatch as H, ImmutableMap as I, DevframeScopedNodeRpc as J, Thenable as K, ImmutableObject as L, createStreamReader as M, createStreamSink as N, StreamErrorPayload as O, parseCliFlags as Ot, Immutable as P, DevframeSettingsStore as Q, ImmutableSet as R, RpcStreamingChannel as S, EventEmitter as St, BufferedChunk as T, CliFlagsSchema as Tt, createSharedState as U, SharedStateOptions as V, EntriesToObject as W, DevframeSettings as X, DevframeScopedStreamingHost as Y, DevframeSettingsRegistry as Z, DevframeNodeRpcSession as _, AgentResourceInput as _t, DevframeDockDefaults as a, DevframeRpcClientFunctions as at, RpcSharedStateGetOptions as b, DevframeAgentHost as bt, DevframeSetupInfo as c, DevframeHost as ct, McpRouteOptions as d, DevframeDiagnosticsHost as dt, ScopedClientFunctions as et, defineDevframe as f, DevframeDiagnosticsLogger as ft, DevframeNodeContext as g, AgentResourceContent as gt, DevframeCapabilities as h, AgentResource as ht, DevframeDeploymentKind as i, DevframeViewHost as it, StreamSinkEvents as j, StreamReader as k, DevframeSpaOptions as l, DevframeDefineDiagnosticsOptions as lt, ConnectionMetaWebsocket as m, AgentManifest as mt, DevframeCliOptions as n, ScopedSharedStates as nt, DevframeDuplicationStrategy as o, DevframeRpcServerFunctions as ot, ConnectionMeta as p, AgentHandle as pt, DevframeScopedNodeContext as q, DevframeDefinition as r, SettingsForNamespace as rt, DevframeRuntime as s, DevframeRpcSharedStates as st, DevframeBrowserContext as t, ScopedServerFunctions as tt, DevframeWsOptions as u, DevframeDiagnosticsDefinition as ut, RpcBroadcastOptions as v, AgentTool as vt, RpcStreamingHost as w, EventsMap as wt, RpcSharedStateHost as x, DevframeAgentHostEvents as xt, RpcFunctionsHost as y, AgentToolInput as yt, SharedState as z };
+export { DevframeRpcSharedStates as $, DevframeSettingsStore as A, EventsMap as At, DevframeDiagnosticsDefinition as B, DevframeServicesHost as C, AgentResourceInput as Ct, DevframeScopedStreamingHost as D, DevframeAgentHostEvents as Dt, DevframeScopedNodeRpc as E, DevframeAgentHost as Et, SettingsForNamespace as F, RpcFunctionsHost as G, DevframeDiagnosticsLogger as H, DevframeViewHost as I, RpcStreamingChannel as J, RpcSharedStateGetOptions as K, DevframeHost as L, ScopedClientFunctions as M, InferCliFlags as Mt, ScopedServerFunctions as N, defineCliFlags as Nt, DevframeSettings as O, EventEmitter as Ot, ScopedSharedStates as P, parseCliFlags as Pt, DevframeRpcServerFunctions as Q, DevframeStorageScope as R, DevframeServiceOf as S, AgentResourceContent as St, DevframeScopedNodeContext as T, AgentToolInput as Tt, DevframeNodeRpcSession as U, DevframeDiagnosticsHost as V, RpcBroadcastOptions as W, RpcStreamingHost as X, RpcStreamingChannelOptions as Y, DevframeRpcClientFunctions as Z, ConnectionMeta as _, SharedStatePatch as _t, DevframeDockDefaults as a, StreamSink as at, DevframeNodeContext as b, AgentManifest as bt, DevframeSetupInfo as c, createStreamSink as ct, McpRouteOptions as d, ImmutableMap as dt, BufferedChunk as et, defineDevframe as f, ImmutableObject as ft, Thenable as g, SharedStateOptions as gt, PartialWithoutId as h, SharedStateEvents as ht, DevframeDeploymentKind as i, StreamReader as it, ScopedBroadcastOptions as j, CliFlagsSchema as jt, DevframeSettingsRegistry as k, EventUnsubscribe as kt, DevframeSpaOptions as l, Immutable as lt, EntriesToObject as m, SharedState as mt, DevframeCliOptions as n, CreateStreamSinkOptions as nt, DevframeDuplicationStrategy as o, StreamSinkEvents as ot, DevframeAuthHandler as p, ImmutableSet as pt, RpcSharedStateHost as q, DevframeDefinition as r, StreamErrorPayload as rt, DevframeRuntime as s, createStreamReader as st, DevframeBrowserContext as t, CreateStreamReaderOptions as tt, DevframeWsOptions as u, ImmutableArray as ut, ConnectionMetaWebsocket as v, createSharedState as vt, DevframeServicesRegistry as w, AgentTool as wt, DevframeServiceId as x, AgentResource as xt, DevframeCapabilities as y, AgentHandle as yt, DevframeDefineDiagnosticsOptions as z };