devframe 0.9.0-beta.9 → 0.9.1

package/dist/{devframe-DJMg0WLe.d.mts → devframe-BlLEZR-x.d.mts}

@@ -493,734 +493,874 @@ declare function createStreamSink<T>(options?: CreateStreamSinkOptions): StreamS
  */
 declare function createStreamReader<T>(options?: CreateStreamReaderOptions): StreamReader<T>;
 //#endregion
-//#region src/types/rpc-augments.d.ts
+//#region src/types/diagnostics.d.ts
 /**
- * To be extended
+ * 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 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>;
-  /**
-   * Streaming chunk pushed from server to subscribed clients. Wired by
-   * `RpcStreamingHost`; do not register manually.
-   *
-   * @internal
-   */
-  'devframe:streaming:chunk': (channel: string, id: string, seq: number, chunk: any) => Promise<void>;
-  /**
-   * Streaming terminator pushed from server to subscribed clients. Wired by
-   * `RpcStreamingHost`; do not register manually.
-   *
-   * @internal
-   */
-  'devframe:streaming:end': (channel: string, id: string, error?: {
-    name: string;
-    message: string;
-  }) => Promise<void>;
-  /**
-   * Server→client cancel for an in-flight upload. Wired by
-   * `RpcStreamingHost`; do not register manually.
-   *
-   * @internal
-   */
-  '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>;
-}
+type DevframeDiagnosticsLogger = Record<string, any>;
 /**
- * To be extended
+ * 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 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;
-  }>;
+interface DevframeDiagnosticsHost {
   /**
-   * 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
+   * 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.
    */
-  'anonymous:devframe:auth:exchange': (params: {
-    code: string;
-    ua: string;
-    origin: string;
-  }) => Promise<{
-    authToken: string | null;
-  }>;
+  readonly logger: DevframeDiagnosticsLogger;
   /**
-   * 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
+   * 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.
    */
-  'devframe:auth:revoke': () => Promise<void>;
+  register: (definitions: Record<string, unknown>) => void;
   /**
-   * Subscribe a client to a shared-state key. Wired by
-   * `RpcSharedStateHost`; do not register manually.
-   *
-   * @internal
+   * Build a typed diagnostics object with the host's ANSI console reporter
+   * pre-wired. The same `devframe/utils/nostics` `defineDiagnostics` every
+   * built-in plugin's module-level `diagnostics.ts` uses, so integrations
+   * don't need to take a direct dependency on `nostics`.
    */
-  'devframe:rpc:server-state:subscribe': (key: string) => Promise<void>;
+  defineDiagnostics: typeof defineDiagnostics;
+}
+//#endregion
+//#region src/types/host.d.ts
+interface DevframeHost {
   /**
-   * Read the current value for a shared-state key. Wired by
-   * `RpcSharedStateHost`; do not register manually.
-   *
-   * @internal
+   * Serve static assets at the given URL base — a local directory, or a
+   * resolved {@link RemoteAssetsStore} back-proxy. Called by
+   * `DevframeViewHost.hostStatic` (which normalizes `RemoteAssets`
+   * declarations into stores first). Implementations map this to whatever
+   * the underlying runtime expects (Vite middleware, h3 handler, no-op
+   * for build snapshots) — the shared engine in
+   * `devframe/utils/serve-static` accepts either shape.
    */
-  'devframe:rpc:server-state:get': (key: string) => Promise<any>;
+  mountStatic: (base: string, source: string | RemoteAssetsStore) => void | Promise<void>;
   /**
-   * Replace a shared-state value (from the client). Wired by
-   * `RpcSharedStateHost`; do not register manually.
+   * 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.
    *
-   * @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.
+   * Called by `ctx.install` 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.
    *
-   * @internal
+   * 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.
    */
-  'devframe:rpc:server-state:patch': (key: string, patches: any[], syncId: string) => Promise<void>;
+  mountConnectionMeta?: (base: string) => void | Promise<void>;
   /**
-   * Client→server streaming subscription with optional replay cursor.
-   * Wired by `RpcStreamingHost`; do not register manually.
-   *
-   * @internal
+   * 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.
    */
-  'devframe:streaming:subscribe': (channel: string, id: string, opts?: {
-    afterSeq?: number;
-  }) => Promise<void>;
+  resolveOrigin: () => string;
   /**
-   * Client→server streaming unsubscribe. Wired by `RpcStreamingHost`;
-   * do not register manually.
+   * 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`).
    *
-   * @internal
-   */
-  'devframe:streaming:unsubscribe': (channel: string, id: string) => Promise<void>;
-  /**
-   * Client→server streaming cancellation request. Wired by
-   * `RpcStreamingHost`; do not register manually.
+   *   - `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/`.
    *
-   * @internal
+   * Implementations should ensure the directory exists or be safe to
+   * pass to a downstream `createStorage(...)` call that creates it
+   * lazily.
    */
-  'devframe:streaming:cancel': (channel: string, id: string) => Promise<void>;
+  getStorageDir: (scope: DevframeStorageScope) => string;
+}
+/**
+ * Storage placement classes for {@link DevframeHost.getStorageDir}:
+ * `workspace` is committable and team-shared, `project` is per-checkout
+ * private, `global` is per-user.
+ */
+type DevframeStorageScope = 'workspace' | 'project' | 'global';
+//#endregion
+//#region src/types/views.d.ts
+interface DevframeViewHost {
   /**
-   * 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>;
+  buildStaticDirs: {
+    baseUrl: string;
+    source: StaticAssetsSource;
+  }[];
   /**
-   * Client→server upload terminator. Wired by `RpcStreamingHost`; do not
-   * register manually.
+   * Helper to host static files
+   * - In `dev` mode, it will register middleware to `viteServer.middlewares` to host the static files
+   * - In `build` mode, it will copy the static files to the dist directory
    *
-   * @internal
+   * Accepts a local dist directory, or a {@link StaticAssetsSource} remote
+   * declaration served through devframe's caching CDN back-proxy.
    */
-  'devframe:streaming:upload-end': (channel: string, id: string, error?: {
-    name: string;
-    message: string;
-  }) => Promise<void>;
+  hostStatic: (baseUrl: string, source: StaticAssetsSource) => void;
 }
+//#endregion
+//#region src/types/scope.d.ts
+type AnyRpcFn = (...args: any[]) => any;
 /**
- * To be extended
+ * 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.
  */
-interface DevframeRpcSharedStates {}
-//#endregion
-//#region src/types/rpc.d.ts
-interface DevframeNodeRpcSession {
-  meta: DevframeNodeRpcSessionMeta;
-  rpc: BirpcReturn<DevframeRpcClientFunctions, DevframeRpcServerFunctions, false>;
+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>;
 }
-interface RpcBroadcastOptions<METHOD, Args extends any[]> {
+/**
+ * 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;
-  filter?: (client: BirpcReturn<DevframeRpcClientFunctions, DevframeRpcServerFunctions, false>) => boolean | void;
 }
-type RpcFunctionsHost = RpcFunctionsCollectorBase<DevframeRpcServerFunctions, DevframeNodeContext> & {
-  /**
-   * Invoke a locally registered server RPC function directly.
-   *
-   * 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]>>>;
+/**
+ * Node-side streaming host scoped to a namespace. Channel names are
+ * auto-prefixed with `<namespace>:`.
+ */
+interface DevframeScopedStreamingHost {
   /**
-   * Broadcast a message to all connected clients
+   * 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.
    */
-  broadcast: <T extends keyof DevframeRpcClientFunctions, Args extends Parameters<DevframeRpcClientFunctions[T]>>(options: RpcBroadcastOptions<T, Args>) => Promise<void>;
+  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;
   /**
-   * Get the current RPC client
-   *
-   * Available in RPC functions to get the current RPC client
+   * 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.
    */
-  getCurrentRpcSession: () => DevframeNodeRpcSession | undefined;
+  register: (fn: RpcFunctionDefinition<string, any, any, any, any, any, DevframeNodeContext>, force?: boolean) => void;
   /**
-   * The shared state host
+   * Update a previously registered server RPC function. Same naming rules
+   * as {@link DevframeScopedNodeRpc.register}.
    */
-  sharedState: RpcSharedStateHost;
+  update: (fn: RpcFunctionDefinition<string, any, any, any, any, any, DevframeNodeContext>, force?: boolean) => void;
   /**
-   * The streaming channel host. Provides per-channel `start()` /
-   * `pipeFrom()` producers; clients consume via `rpc.streaming.subscribe()`.
-   *
-   * @see RpcStreamingHost
+   * 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.
    */
-  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[];
+  call: {
+    <T extends keyof ScopedServerFunctions<NS> & string>(method: T, ...args: Parameters<ScopedRpcFn<DevframeRpcServerFunctions, NS, T>>): Promise<Awaited<ReturnType<ScopedRpcFn<DevframeRpcServerFunctions, NS, T>>>>;
+    <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>;
+  };
   /**
-   * 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.
+   * Broadcast a client RPC event to every connected client. Bare method
+   * names are resolved within this namespace.
    */
-  onKeyAdded: (fn: (key: string) => void) => () => void;
+  broadcast: {
+    <T extends keyof ScopedClientFunctions<NS> & string>(options: ScopedBroadcastOptions<T, Parameters<ScopedRpcFn<DevframeRpcClientFunctions, NS, T>>>): Promise<void>;
+    (options: ScopedBroadcastOptions<string, any[]>): Promise<void>;
+  };
   /**
-   * 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.
+   * Resolve a namespaced shared state. Bare keys are resolved within this
+   * namespace; pass a fully-qualified key (containing `:`) to opt out.
    */
-  delete: (key: string) => boolean;
+  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.
+ * Augmentation point mapping service ids to their implementation types.
+ * Providers extend this via `declare module 'devframe'`.
+ */
+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;
+/**
+ * Augmentation point mapping a service's npm package name to the RPC scope
+ * namespace it registers its functions under, so a client's
+ * `services.get('@devframes/service-x')` returns a scoped RPC surface typed
+ * against that namespace. Service packages contribute their entry via
+ * declaration merging:
  *
- * @see {@link https://devfra.me/guide/streaming Streaming guide}
+ * ```ts
+ * declare module 'devframe' {
+ *   interface DevframeServicesScopeRegistry {
+ *     '@devframes/service-open': 'devframes:service:open'
+ *   }
+ * }
+ * ```
  */
-interface RpcStreamingChannel<T = unknown> {
-  /** Channel name as registered with `ctx.rpc.streaming.create()`. */
-  readonly name: string;
+interface DevframeServicesScopeRegistry {}
+/** Resolved RPC scope namespace for a service package name, or `string`. */
+type DevframeServiceScopeOf<PKG> = PKG extends keyof DevframeServicesScopeRegistry ? DevframeServicesScopeRegistry[PKG] & string : string;
+/**
+ * A **wire service** — a shared server-side capability (e.g. open-in-editor,
+ * syntax highlighting) packaged so any devframe host can install it once and
+ * every plugin/client can consume it without re-implementing or re-bundling
+ * it. Contrast with plain {@link DevframeServicesHost.provide}, which shares
+ * an in-process object between plugins on the node side only: a
+ * `DevframeServiceDefinition` additionally registers RPC functions under its
+ * {@link DevframeServiceDefinition.scope} and is **advertised to clients**
+ * through the reactive `devframe:services` shared state, so browser UIs can
+ * feature-detect it (`ctx.services.has(pkg)`) and degrade gracefully.
+ *
+ * Ship one per npm package (`@devframes/service-<slug>` for first-party),
+ * with the package's default export being the `create<X>Service` factory —
+ * never a pre-built instance.
+ */
+interface DevframeServiceDefinition<API = unknown, Options = any> {
   /**
-   * 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.
+   * The npm package name this service ships in — also its registry key
+   * (`ctx.services.has('@devframes/service-x')` on both node and client).
    */
-  start: (opts?: {
-    id?: string;
-  }) => StreamSink<T>;
+  package: string;
+  /** Semver of the service — advertised to clients, checked against descriptor ranges. */
+  version: string;
   /**
-   * 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.
+   * RPC namespace the service's functions register under, following the
+   * plugin id grammar (e.g. `devframes:service:open`). `setup` receives a
+   * context pre-scoped to it, so functions register with bare names.
    */
-  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[];
+  scope: 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.
+   * Extra advertised metadata (feature flags, defaults, …). Must be
+   * JSON-serializable — it is mirrored to every client.
    */
-  openInbound: (opts?: {
-    id?: string;
-  }) => StreamReader<T>;
+  meta?: Record<string, unknown>;
+  /**
+   * This instance's own option set (usually baked in by the factory that
+   * created the definition). Joins the merge alongside every declarative
+   * descriptor's `options`.
+   */
+  options?: Options;
+  /**
+   * Merge the option sets contributed by multiple installers (in declaration
+   * order) into the one bag passed to `setup`. Defaults to a shallow merge
+   * where later sets win.
+   */
+  mergeOptions?: (sets: Options[]) => Options;
+  /**
+   * Construct the service: register its RPC functions on the pre-scoped
+   * context and return its **node API** — the in-process surface other
+   * plugins get from `ctx.services.get(package)` (no RPC hop server-side).
+   * `info.options` carries every installer's option sets merged at the
+   * `ready()` barrier (via {@link mergeOptions} when present, otherwise a
+   * shallow merge in declaration order — later sets win).
+   */
+  setup: (ctx: DevframeScopedNodeContext, info: {
+    options?: Options;
+  }) => API | Promise<API>;
 }
 /**
- * Server-side streaming host. Lives on `ctx.rpc.streaming` alongside
- * `ctx.rpc.sharedState`. Each named channel owns its own stream registry
- * and wire namespace.
+ * Declarative reference to a service package — the form a
+ * {@link DevframeServiceInput} takes when the installer doesn't hold the
+ * factory itself (e.g. `DevframeDefinition.services`). The host imports the
+ * package's default-export factory and installs the resulting definition at
+ * the `ready()` barrier.
  */
-interface RpcStreamingHost {
+interface DevframeServiceDescriptor<Options = any> {
+  /** npm package name of the service (its default export is the factory). */
+  package: string;
   /**
-   * Register a streaming channel. Names follow the `<plugin-id>:<channel>`
-   * convention (e.g. `'my-devtool:chat-stream'`). Throws `DF0032` if the
-   * name is already taken.
+   * Accepted semver range for the installed service. An unsatisfied range
+   * warns (`DF0069`) — or throws (`DF0068`) when {@link required} — while the
+   * service still installs; the advertised meta carries the real version.
    */
-  create: <T = unknown>(name: string, opts?: RpcStreamingChannelOptions) => RpcStreamingChannel<T>;
+  version?: string;
   /**
-   * Adapters call this when a session disconnects so the host can drop
-   * subscribers and abort orphaned streams. Most users do not need this;
-   * it's wired by the RPC server binding automatically.
+   * Fail hard when the service can't be imported or its version range isn't
+   * satisfied. By default a missing service is skipped silently — clients see
+   * `has() === false` and degrade.
    *
-   * @internal
+   * @default false
    */
-  _onSessionDisconnected: (meta: DevframeNodeRpcSessionMeta) => void;
+  required?: boolean;
+  /** Option set this installer contributes to the merge. */
+  options?: Options;
 }
-//#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.
+ * What can be passed to `ctx.services.install()` (and listed in
+ * `DevframeDefinition.services`): a declarative {@link DevframeServiceDescriptor}
+ * (the host imports the factory) or a ready {@link DevframeServiceDefinition}
+ * (the installer already called the factory — its `options` join the merge).
  */
-type DevframeDiagnosticsLogger = Record<string, any>;
+type DevframeServiceInput<API = unknown, Options = any> = DevframeServiceDescriptor<Options> | DevframeServiceDefinition<API, Options>;
 /**
- * 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()
- * ```
+ * One service's advertisement entry, mirrored to clients through the
+ * `devframe:services` shared state.
  */
-interface DevframeDiagnosticsHost {
+interface DevframeServiceMeta {
+  /** npm package name — the registry key. */
+  package: string;
+  /** Installed version of the service. */
+  version: string;
+  /** RPC namespace its functions live under. */
+  scope: string;
+  /** Extra service-declared metadata. */
+  meta?: Record<string, unknown>;
+}
+/**
+ * Shape of the `devframe:services` shared state: package name → advertisement.
+ */
+type DevframeServicesState = Record<string, DevframeServiceMeta>;
+interface DevframeServicesHost {
   /**
-   * 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.
+   * Publish a service under a namespaced id. Throws `DF0037` when the id is
+   * already provided (revoke first to replace). Returns a revoke function.
    */
-  readonly logger: DevframeDiagnosticsLogger;
+  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;
   /**
-   * 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.
+   * 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.
    */
-  register: (definitions: Record<string, unknown>) => void;
+  whenAvailable: <ID extends DevframeServiceId>(id: ID, callback: (service: DevframeServiceOf<ID>) => void) => () => void;
+  /** Ids of every currently-provided service. */
+  keys: () => string[];
   /**
-   * Build a typed diagnostics object with the host's ANSI console reporter
-   * pre-wired. The same `devframe/utils/nostics` `defineDiagnostics` every
-   * built-in plugin's module-level `diagnostics.ts` uses, so integrations
-   * don't need to take a direct dependency on `nostics`.
-   */
-  defineDiagnostics: typeof defineDiagnostics;
+   * Install a **wire service** (see {@link DevframeServiceDefinition}).
+   * Before {@link DevframeServicesHost.ready} fires, installs are queued —
+   * option sets from every installer accumulate and each service is
+   * constructed **once** at the barrier with the merged options; the
+   * returned promise resolves with the service's node API then (or
+   * `undefined` when an optional descriptor's package can't be imported).
+   * After the barrier, installs construct immediately; installing an
+   * already-installed package returns the existing API (a warning is
+   * emitted when the late install carried options, since they're ignored).
+   *
+   * `resolveFrom` is where a descriptor's package resolves **from**: a path
+   * or file URL (e.g. `import.meta.url`), or an npm package name — typically
+   * the declaring plugin's `packageName`, so its declared services resolve
+   * against the plugin's own dependencies. Falls back to the context's
+   * `workspaceRoot`.
+   */
+  install: <API = unknown, Options = any>(input: DevframeServiceInput<API, Options>, options?: {
+    resolveFrom?: string | null;
+  }) => Promise<API | undefined>;
+  /**
+   * Fire the collect-then-setup barrier: resolve every queued descriptor
+   * (importing its package), merge option sets per service, construct each
+   * service once, `provide()` its node API under the package name, and
+   * advertise it to clients via the `devframe:services` shared state.
+   * Idempotent — adapters call it once after every devframe's `setup` has
+   * run; a repeat returns the same promise. Rejects when a `required`
+   * service fails to import or misses its version range.
+   */
+  ready: () => Promise<void>;
 }
 //#endregion
-//#region src/types/host.d.ts
-interface DevframeHost {
+//#region src/types/rpc-augments.d.ts
+/**
+ * To be extended
+ */
+interface DevframeRpcClientFunctions {
   /**
-   * Serve static assets at the given URL base — a local directory, or a
-   * resolved {@link RemoteAssetsStore} back-proxy. Called by
-   * `DevframeViewHost.hostStatic` (which normalizes `RemoteAssets`
-   * declarations into stores first). Implementations map this to whatever
-   * the underlying runtime expects (Vite middleware, h3 handler, no-op
-   * for build snapshots) — the shared engine in
-   * `devframe/utils/serve-static` accepts either shape.
+   * Server→client notification that this connection's auth token has been
+   * revoked. The client drops to untrusted on receipt. Broadcast by
+   * `revokeActiveConnectionsForToken`.
+   *
+   * @internal
    */
-  mountStatic: (base: string, source: string | RemoteAssetsStore) => void | Promise<void>;
+  'devframe:auth:revoked': () => Promise<void>;
   /**
-   * 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.
+   * Streaming chunk pushed from server to subscribed clients. Wired by
+   * `RpcStreamingHost`; do not register manually.
    *
-   * Called by `ctx.install` 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.
+   * @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.
    *
-   * 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.
+   * @internal
    */
-  mountConnectionMeta?: (base: string) => void | Promise<void>;
+  'devframe:streaming:end': (channel: string, id: string, error?: {
+    name: string;
+    message: string;
+  }) => Promise<void>;
   /**
-   * 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.
+   * Server→client cancel for an in-flight upload. Wired by
+   * `RpcStreamingHost`; do not register manually.
+   *
+   * @internal
    */
-  resolveOrigin: () => string;
+  'devframe:streaming:upload-cancel': (channel: string, id: string) => Promise<void>;
   /**
-   * 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`).
+   * Full shared-state snapshot pushed from server to subscribed clients.
+   * Wired by `RpcSharedStateHost`; do not register manually.
    *
-   *   - `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/`.
+   * @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.
    *
-   * Implementations should ensure the directory exists or be safe to
-   * pass to a downstream `createStorage(...)` call that creates it
-   * lazily.
+   * @internal
    */
-  getStorageDir: (scope: DevframeStorageScope) => string;
+  'devframe:rpc:client-state:patch': (key: string, patches: any[], syncId: string) => Promise<void>;
 }
 /**
- * Storage placement classes for {@link DevframeHost.getStorageDir}:
- * `workspace` is committable and team-shared, `project` is per-checkout
- * private, `global` is per-user.
+ * To be extended
  */
-type DevframeStorageScope = 'workspace' | 'project' | 'global';
-//#endregion
-//#region src/types/views.d.ts
-interface DevframeViewHost {
+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
    */
-  buildStaticDirs: {
-    baseUrl: string;
-    source: StaticAssetsSource;
-  }[];
+  'anonymous:devframe:auth': (params: {
+    authToken: string;
+    ua: string;
+    origin: string;
+  }) => Promise<{
+    isTrusted: boolean;
+  }>;
   /**
-   * 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
+   * 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`.
    *
-   * Accepts a local dist directory, or a {@link StaticAssetsSource} remote
-   * declaration served through devframe's caching CDN back-proxy.
+   * Named with the `anonymous:` prefix (see `isAnonymousRpcMethod`) so it is
+   * reachable before the connection is trusted.
+   *
+   * @internal
    */
-  hostStatic: (baseUrl: string, source: StaticAssetsSource) => 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>>;
+  'anonymous:devframe:auth:exchange': (params: {
+    code: string;
+    ua: string;
+    origin: string;
+  }) => Promise<{
+    authToken: string | null;
+  }>;
   /**
-   * Subscribe to settings changes. Resolves to an unsubscribe function.
-   * Fires on every local or remote mutation with the full snapshot.
+   * 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
    */
-  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]; };
+  '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>;
+}
 /**
- * Broadcast options for a scoped client method (bare name).
+ * To be extended
  */
-interface ScopedBroadcastOptions<METHOD, Args extends any[]> {
+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/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;
 }
-/**
- * Node-side streaming host scoped to a namespace. Channel names are
- * auto-prefixed with `<namespace>:`.
- */
-interface DevframeScopedStreamingHost {
+type RpcFunctionsHost = RpcFunctionsCollectorBase<DevframeRpcServerFunctions, DevframeNodeContext> & {
   /**
-   * 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.
+   * Invoke a locally registered server RPC function directly.
+   *
+   * This bypasses transport and is useful for server-side cross-function calls.
    */
-  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;
+  invokeLocal: <T extends keyof DevframeRpcServerFunctions, Args extends Parameters<DevframeRpcServerFunctions[T]>>(method: T, ...args: Args) => Promise<Awaited<ReturnType<DevframeRpcServerFunctions[T]>>>;
   /**
-   * 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 a message to all connected clients
    */
-  register: (fn: RpcFunctionDefinition<string, any, any, any, any, any, DevframeNodeContext>, force?: boolean) => void;
+  broadcast: <T extends keyof DevframeRpcClientFunctions, Args extends Parameters<DevframeRpcClientFunctions[T]>>(options: RpcBroadcastOptions<T, Args>) => Promise<void>;
   /**
-   * Update a previously registered server RPC function. Same naming rules
-   * as {@link DevframeScopedNodeRpc.register}.
+   * Get the current RPC client
+   *
+   * Available in RPC functions to get the current RPC client
    */
-  update: (fn: RpcFunctionDefinition<string, any, any, any, any, any, DevframeNodeContext>, force?: boolean) => void;
+  getCurrentRpcSession: () => DevframeNodeRpcSession | undefined;
   /**
-   * 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.
+   * The shared state host
    */
-  call: {
-    <T extends keyof ScopedServerFunctions<NS> & string>(method: T, ...args: Parameters<ScopedRpcFn<DevframeRpcServerFunctions, NS, T>>): Promise<Awaited<ReturnType<ScopedRpcFn<DevframeRpcServerFunctions, NS, T>>>>;
-    <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>;
-  };
+  sharedState: RpcSharedStateHost;
   /**
-   * Broadcast a client RPC event to every connected client. Bare method
-   * names are resolved within this namespace.
+   * The streaming channel host. Provides per-channel `start()` /
+   * `pipeFrom()` producers; clients consume via `rpc.streaming.subscribe()`.
+   *
+   * @see RpcStreamingHost
    */
-  broadcast: {
-    <T extends keyof ScopedClientFunctions<NS> & string>(options: ScopedBroadcastOptions<T, Parameters<ScopedRpcFn<DevframeRpcClientFunctions, NS, T>>>): Promise<void>;
-    (options: ScopedBroadcastOptions<string, any[]>): Promise<void>;
-  };
+  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[];
   /**
-   * Resolve a namespaced shared state. Bare keys are resolved within this
-   * namespace; pass a fully-qualified key (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.
    */
-  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;
+  onKeyAdded: (fn: (key: string) => void) => () => void;
+  /**
+   * 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.
+   */
+  delete: (key: string) => boolean;
 }
 /**
- * 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.
+ * Options for `RpcStreamingHost.create()`.
  */
-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 RpcStreamingChannelOptions {
   /**
-   * Return a new scoped context, replacing the current scope. Pass `null`
-   * or `''` to un-scope and get the base context.
+   * 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.
    */
-  scope: DevframeNodeContext['scope'];
+  replayWindow?: number;
+  /**
+   * 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.
+   */
+  closedStreamRetention?: number;
 }
-//#endregion
-//#region src/types/services.d.ts
 /**
- * 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.
- *
- * 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 })
- * })
- * ```
+ * Channel handle returned by `ctx.rpc.streaming.create(name, opts)`. A
+ * channel owns a wire namespace; calling `start()` produces individual
+ * streams keyed by id.
  *
- * Service ids follow the same namespacing rule as RPC functions: prefix with
- * the providing plugin's id.
- */
-/**
- * Augmentation point mapping service ids to their implementation types.
- * Providers extend this via `declare module 'devframe'`.
+ * @see {@link https://devfra.me/guide/streaming Streaming guide}
  */
-interface DevframeServicesRegistry {}
+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>;
+}
 /**
- * A known (augmented) service id, or any namespaced string for services
- * without a published type augmentation.
+ * Server-side streaming host. Lives on `ctx.rpc.streaming` alongside
+ * `ctx.rpc.sharedState`. Each named channel owns its own stream registry
+ * and wire namespace.
  */
-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 {
+interface RpcStreamingHost {
   /**
-   * Publish a service under a namespaced id. Throws `DF0037` when the id is
-   * already provided (revoke first to replace). Returns a revoke function.
+   * 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.
    */
-  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;
+  create: <T = unknown>(name: string, opts?: RpcStreamingChannelOptions) => RpcStreamingChannel<T>;
   /**
-   * 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.
+   * 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
    */
-  whenAvailable: <ID extends DevframeServiceId>(id: ID, callback: (service: DevframeServiceOf<ID>) => void) => () => void;
-  /** Ids of every currently-provided service. */
-  keys: () => string[];
+  _onSessionDisconnected: (meta: DevframeNodeRpcSessionMeta) => void;
 }
 //#endregion
 //#region src/types/context.d.ts
@@ -1841,9 +1981,22 @@ interface DevframeDefinition {
     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[];
   /** Server-side setup — the primary entrypoint. Runs in every runtime. */
   setup: (ctx: DevframeNodeContext, info?: DevframeSetupInfo) => void | Promise<void>;
   cli?: DevframeCliOptions;
 }
 //#endregion
-export { StreamReader as $, ScopedServerFunctions as A, defineCliFlags as At, RpcFunctionsHost as B, DevframeScopedStreamingHost as C, DevframeAgentHost as Ct, ScopedBroadcastOptions as D, EventsMap as Dt, DevframeSettingsStore as E, EventUnsubscribe as Et, DevframeStorageScope as F, RpcStreamingHost as G, RpcSharedStateHost as H, DevframeDiagnosticsHost as I, DevframeRpcSharedStates as J, DevframeRpcClientFunctions as K, DevframeDiagnosticsLogger as L, SettingsForNamespace as M, DevframeViewHost as N, ScopedClientFunctions as O, CliFlagsSchema as Ot, DevframeHost as P, StreamErrorPayload as Q, DevframeNodeRpcSession as R, DevframeScopedNodeRpc as S, AgentToolProviderHandle as St, DevframeSettingsRegistry as T, EventEmitter as Tt, RpcStreamingChannel as U, RpcSharedStateGetOptions as V, RpcStreamingChannelOptions as W, CreateStreamReaderOptions as X, BufferedChunk as Y, CreateStreamSinkOptions as Z, DevframeServiceId as _, AgentResourceContent as _t, DevframeDuplicationStrategy as a, ImmutableArray as at, DevframeServicesRegistry as b, AgentToolInput as bt, DevframeWsOptions as c, ImmutableSet as ct, ConnectionMeta as d, SharedStateOptions as dt, StreamSink as et, ConnectionMetaSse as f, SharedStatePatch as ft, DevframeNodeContext as g, AgentResource as gt, DevframeConnectionConfigsRegistry as h, AgentManifest as ht, DevframeDockDefaults as i, Immutable as it, ScopedSharedStates as j, parseCliFlags as jt, ScopedRpcFn as k, InferCliFlags as kt, McpRouteOptions as l, SharedState as lt, DevframeCapabilities as m, AgentHandle as mt, DevframeDefinition as n, createStreamReader as nt, DevframeSetupInfo as o, ImmutableMap as ot, ConnectionMetaWebsocket as p, createSharedState as pt, DevframeRpcServerFunctions as q, DevframeDeploymentKind as r, createStreamSink as rt, DevframeSseOptions as s, ImmutableObject as st, DevframeCliOptions as t, StreamSinkEvents as tt, DevframeAuthHandler as u, SharedStateEvents as ut, DevframeServiceOf as v, AgentResourceInput as vt, DevframeSettings as w, DevframeAgentHostEvents as wt, DevframeScopedNodeContext as x, AgentToolProvider as xt, DevframeServicesHost as y, AgentTool as yt, RpcBroadcastOptions as z };
+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 };