@super-line/server 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,7 +1,14 @@
 import { Server, IncomingMessage } from 'node:http';
-import { ServerMessageDef, Serializer, ServerFrame, EmitData, Adapter, Contract, RoleOf, SharedRequests, ServerInput, SharedEvents, Output, RoleRequests, Events, RoleTopics, SharedTopics, ServerEvents, ServerEmit, ServerData } from '@super-line/core';
+import { ServerMessageDef, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, SharedRequests, ServerInput, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, EventData } from '@super-line/core';
 import { WebSocket } from 'ws';
 
+/** Backpressure policy: what to do when a connection's send buffer grows too large. */
+interface Backpressure {
+    /** Buffer size (bytes) above which {@link Backpressure.onExceed} kicks in. */
+    maxBufferedBytes: number;
+    /** `'close'` (default) drops the connection with code 1013; `'drop'` skips the frame. */
+    onExceed?: 'close' | 'drop';
+}
 /**
  * A single client connection, passed to handlers as the third argument.
  *
@@ -10,23 +17,43 @@ import { WebSocket } from 'ws';
  * (use a per-user room instead). Generic over the events it may emit (scoped by
  * role), its `ctx`, and its `role`.
  */
-declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role extends string = string> {
+declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role extends string = string, Data = unknown> {
     /** The underlying `ws` socket. `conn.ws.terminate()` simulates a drop in tests. */
     readonly ws: WebSocket;
+    /** Server-assigned unique id for this connection (stable for its lifetime). */
+    readonly id: string;
     /** This connection's role (the literal resolved by `authenticate`). */
     readonly role: Role;
     /** The context `authenticate` returned for this connection. */
     readonly ctx: Ctx;
     private readonly serializer;
+    private readonly backpressure?;
+    /** Optional inspector tap: called with each `emit` so the server can mirror it to inspectors. */
+    private readonly onEmit?;
     /** Namespaced channels (rooms + topics) this connection belongs to. */
     readonly channels: Set<string>;
+    /** Mutable per-connection scratch state, typed per role by the contract's `data` schema. */
+    data: Data;
+    /** When this connection was accepted (`Date.now()` at the upgrade). */
+    readonly connectedAt: number;
+    /** When the server last sent a heartbeat ping to this connection (managed by the server). */
+    lastPingAt?: number;
+    /** When a heartbeat pong was last received — liveness signal (managed by the server). */
+    lastPongAt?: number;
+    /** Pings sent since the last pong; drives reaping (managed by the server). */
+    missedPongs: number;
     constructor(
     /** The underlying `ws` socket. `conn.ws.terminate()` simulates a drop in tests. */
     ws: WebSocket, 
+    /** Server-assigned unique id for this connection (stable for its lifetime). */
+    id: string, 
     /** This connection's role (the literal resolved by `authenticate`). */
     role: Role, 
     /** The context `authenticate` returned for this connection. */
-    ctx: Ctx, serializer: Serializer);
+    ctx: Ctx, serializer: Serializer, backpressure?: Backpressure | undefined, 
+    /** Optional inspector tap: called with each `emit` so the server can mirror it to inspectors. */
+    onEmit?: ((event: string, data: unknown) => void) | undefined);
+    private overBackpressure;
     /** Encode and send a frame (unicast, e.g. req/res). */
     send(frame: ServerFrame): void;
     /** Forward an already-encoded frame (fan-out path; encoded once at the source). */
@@ -40,9 +67,12 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
 /**
  * In-process pub/sub bus. Share one bus across multiple servers to simulate
  * multiple nodes in a test (each server gets its own adapter bound to the bus).
+ * The presence directory also lives here, so servers sharing a bus see the whole
+ * cluster (mirroring how Redis is shared in production).
  */
 declare class MemoryBus {
     private readonly channels;
+    readonly descriptors: Map<string, ConnDescriptor>;
     subscribe(channel: string, adapter: MemoryAdapter): void;
     unsubscribe(channel: string, adapter: MemoryAdapter): void;
     publish(channel: string, payload: string | Uint8Array): void;
@@ -50,6 +80,7 @@ declare class MemoryBus {
 declare class MemoryAdapter implements Adapter {
     private readonly bus;
     private handler?;
+    readonly presence: PresenceStore;
     constructor(bus: MemoryBus);
     subscribe(channel: string): void;
     unsubscribe(channel: string): void;
@@ -83,10 +114,10 @@ type CtxUnion<A> = A extends {
     ctx: infer X;
 } ? X : never;
 type RoleHandlers<C extends Contract, A, R extends RoleOf<C>> = {
-    [K in keyof RoleRequests<C, R>]: (input: ServerInput<RoleRequests<C, R>[K]>, ctx: CtxFor<A, R>, conn: Conn<Events<C, R>, CtxFor<A, R>, R>) => Awaitable<Output<RoleRequests<C, R>[K]>>;
+    [K in keyof RoleRequests<C, R>]: (input: ServerInput<RoleRequests<C, R>[K]>, ctx: CtxFor<A, R>, conn: Conn<Events<C, R>, CtxFor<A, R>, R, DataOf<C, R>>) => Awaitable<Output<RoleRequests<C, R>[K]>>;
 };
 type SharedHandlers<C extends Contract, A> = {
-    [K in keyof SharedRequests<C>]: (input: ServerInput<SharedRequests<C>[K]>, ctx: CtxUnion<A>, conn: Conn<SharedEvents<C>, CtxUnion<A>, RoleOf<C>>) => Awaitable<Output<SharedRequests<C>[K]>>;
+    [K in keyof SharedRequests<C>]: (input: ServerInput<SharedRequests<C>[K]>, ctx: CtxUnion<A>, conn: Conn<SharedEvents<C>, CtxUnion<A>, RoleOf<C>, AnyData<C>>) => Awaitable<Output<SharedRequests<C>[K]>>;
 };
 /**
  * The handler map passed to `implement`: one block per role plus an optional
@@ -100,12 +131,17 @@ type Handlers<C extends Contract, A> = ([keyof SharedRequests<C>] extends [never
 };
 /** Context passed to middleware and lifecycle hooks about the current operation. */
 interface MiddlewareInfo {
-    /** Whether this is a request or a topic subscribe. */
-    kind: 'request' | 'subscribe';
-    /** The request/topic name. */
+    /** Whether this is a request, a topic subscribe, or a bus event delivery. */
+    kind: 'request' | 'subscribe' | 'event';
+    /** The request/topic/event name. */
     name: string;
-    /** The connection the operation is on (`conn.role` available). */
-    conn: Conn;
+    /** The connection the operation is on, if any (`conn.role` available). Absent for bus events. */
+    conn?: Conn;
+}
+/** Metadata passed to a {@link SuperLineServer.subscribe} callback alongside the event payload. */
+interface BusMeta {
+    /** The node that published the event. Equals `srv.nodeId` for a same-node publish (local echo). */
+    from: string;
 }
 /**
  * Flat middleware run before request/subscribe handlers. Call `next()` to proceed,
@@ -125,14 +161,64 @@ interface Room<C extends Contract> {
     broadcast<E extends keyof SharedEvents<C>>(event: E, data: EmitData<SharedEvents<C>[E]>): void;
     /** Member count **on the current node** (membership is node-local). */
     readonly size: number;
+    /** Snapshot of this room's members **on the current node**. */
+    readonly connections: Conn[];
+}
+/** Synchronous, node-local introspection of the current server process. */
+interface LocalView {
+    /** Snapshot of all connections accepted on this node. */
+    readonly connections: Conn[];
+    /** Names of rooms with at least one member on this node. */
+    readonly rooms: string[];
+    /** Names of topics with at least one subscriber on this node. */
+    readonly topics: string[];
+}
+/**
+ * Asynchronous, cluster-wide introspection backed by the adapter's presence
+ * directory. Methods reject if the configured adapter has no presence support.
+ */
+interface ClusterView {
+    /** Every live connection across the cluster. */
+    connections(): Promise<ConnDescriptor[]>;
+    /** Total live connection count across the cluster. */
+    count(): Promise<number>;
+    /** Connections for a given user key (the `identify` hook). */
+    byUser(userId: string): Promise<ConnDescriptor[]>;
+    /** Connections that are members of `room`, across nodes. */
+    room(name: string): Promise<ConnDescriptor[]>;
+    /** Per-node aggregates (the other nodes and their counts). */
+    topology(): Promise<NodeStat[]>;
+}
+/** A single targeted connection, reachable on whatever node holds it. */
+interface ConnTarget<C extends Contract> {
+    /** Push a shared event to this connection (cross-node). */
+    emit<E extends keyof SharedEvents<C>>(event: E, data: EmitData<SharedEvents<C>[E]>): void;
+    /**
+     * Send a shared server→client request and await the client's typed reply
+     * (cross-node). Rejects with a `TIMEOUT` `SuperLineError` if no live node owns
+     * the connection or the client doesn't answer in time.
+     */
+    request<M extends keyof SharedServerRequests<C>>(name: M, input: ClientInput<SharedServerRequests<C>[M]>, opts?: {
+        timeout?: number;
+        signal?: AbortSignal;
+    }): Promise<Output<SharedServerRequests<C>[M]>>;
+    /** Close this connection (cross-node kick). */
+    close(): void;
+}
+/** All of a user's connections (0..N devices), reachable across nodes. */
+interface UserTarget<C extends Contract> {
+    /** Push a shared event to every one of the user's connections (cross-node). */
+    emit<E extends keyof SharedEvents<C>>(event: E, data: EmitData<SharedEvents<C>[E]>): void;
+    /** Disconnect every one of the user's connections (cross-node). */
+    disconnect(): void;
 }
 /** Lens for role-scoped server sends, returned by `srv.forRole(role)`. */
 interface RoleLens<C extends Contract, R extends RoleOf<C>> {
     /** Publish to a topic in role `R`'s surface (reaches that role's subscribers). */
     publish<T extends keyof RoleTopics<C, R>>(topic: T, data: EmitData<RoleTopics<C, R>[T]>): void;
 }
-/** Options for {@link createSocketServer}. */
-interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
+/** Options for {@link createSuperLineServer}. */
+interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>> {
     /** The `http.Server` to attach to (compose with Express/Fastify/Hono). */
     server?: Server;
     /** Wire serializer; MUST match the client. Defaults to `jsonSerializer`. */
@@ -141,12 +227,41 @@ interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
     adapter?: Adapter;
     /** Only handle upgrades for this pathname; others are left untouched. */
     path?: string;
+    /**
+     * Friendly name for this node, surfaced in `srv.nodeName`, the cluster descriptor, and the
+     * Control Center topology. Defaults to `SUPER_LINE_NODE_NAME` or a short slice of `nodeId`.
+     */
+    nodeName?: string;
     /** Runs at the HTTP upgrade. Return { role, ctx }, or throw to reject with 401. */
     authenticate: (req: IncomingMessage) => Awaitable<A>;
+    /** Stable user key for a connection (powers `cluster.byUser`, `isOnline`, and `toUser`). */
+    identify?: (conn: Conn) => string | undefined;
+    /** Extra fields merged into the connection's cluster descriptor (e.g. `{ plan }`). `ctx` is never auto-serialized. */
+    describeConn?: (conn: Conn) => Record<string, unknown>;
     /** Runs on each client subscribe. Return false or throw to deny. */
     authorizeSubscribe?: (topic: string, ctx: CtxUnion<A>, conn: Conn) => Awaitable<boolean | void>;
     /** Middleware chain run before req/subscribe handlers (rate-limit, authz, logging, metrics). */
     use?: Middleware<A>[];
+    /**
+     * Heartbeat: one timer pings every connection each `interval` ms (updating
+     * `conn.lastPingAt`/`lastPongAt`). Set `maxMissed` to terminate a connection
+     * that misses that many consecutive pongs. `false` disables it.
+     * Defaults to `{ interval: 30_000 }` (no reaping).
+     */
+    heartbeat?: {
+        interval?: number;
+        maxMissed?: number;
+    } | false;
+    /** Guard against slow consumers: when a connection's send buffer exceeds the limit, close or drop. */
+    backpressure?: Backpressure;
+    /**
+     * Read-only Control Center inspector channel, reached via the WS subprotocol
+     * `superline.inspector.v1`. Connections on it bypass `authenticate` and are kept out of
+     * presence, the heartbeat, and `local`/`cluster` results. **Default off; dev / trusted-network only.**
+     */
+    inspector?: boolean | {
+        redact?: string[];
+    };
     /** Called once per accepted connection. */
     onConnection?: (conn: Conn, ctx: CtxUnion<A>) => void;
     /** Called when a connection closes, with the WebSocket close `code`. */
@@ -154,35 +269,52 @@ interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
     /** Called for any error thrown in middleware/handlers (after the client is replied to). */
     onError?: (error: unknown, info: MiddlewareInfo) => void;
 }
-/** A running super-line server, returned by {@link createSocketServer}. */
-interface SocketServer<C extends Contract, A extends AuthResult<C>> {
+/** A running super-line server, returned by {@link createSuperLineServer}. */
+interface SuperLineServer<C extends Contract, A extends AuthResult<C>> {
+    /** This node's stable id (unique per server process). */
+    readonly nodeId: string;
+    /** This node's friendly name (from `nodeName`/`SUPER_LINE_NODE_NAME`, else a short `nodeId` slice). */
+    readonly nodeName: string;
+    /** Synchronous, node-local introspection (connections, rooms, topics on this process). */
+    readonly local: LocalView;
+    /** Asynchronous, cluster-wide introspection backed by the adapter's presence directory. */
+    readonly cluster: ClusterView;
+    /** Whether a user (by `identify` key) has at least one live connection anywhere. */
+    isOnline(userId: string): Promise<boolean>;
+    /** Target a single connection by id, on whatever node holds it (cross-node emit/close). */
+    toConn(id: string): ConnTarget<C>;
+    /** Target all of a user's connections (by `identify` key) across nodes (emit/disconnect). */
+    toUser(userId: string): UserTarget<C>;
     /** Register handlers for shared + per-role requests (chainable). */
-    implement(handlers: Handlers<C, A>): SocketServer<C, A>;
+    implement(handlers: Handlers<C, A>): SuperLineServer<C, A>;
     /** Mixed-role connection group; broadcast() sends a shared contract event to members. */
     room(name: string): Room<C>;
     /** Publish a SHARED topic to all subscribers (server-only publish). */
     publish<T extends keyof SharedTopics<C>>(topic: T, data: EmitData<SharedTopics<C>[T]>): void;
+    /**
+     * Subscribe SERVER-side to a shared topic, cluster-wide. The callback fires for a
+     * publish from any node — including this one (local echo, delivered in-process with
+     * no round-trip). `meta.from` is the publishing node; self-exclude with
+     * `if (meta.from === srv.nodeId) return`. Returns an unsubscribe fn.
+     */
+    subscribe<T extends keyof SharedTopics<C>>(topic: T, handler: (data: EventData<SharedTopics<C>[T]>, meta: BusMeta) => void): () => void;
     /** Lens for role-scoped sends, e.g. forRole('user').publish('feed', data). */
     forRole<R extends RoleOf<C>>(role: R): RoleLens<C, R>;
-    /** Broadcast a typed event to all OTHER server nodes (at-most-once, excludes self). */
-    emitServer<E extends keyof ServerEvents<C>>(event: E, data: ServerEmit<ServerEvents<C>[E]>): void;
-    /** Listen for inter-server events from other nodes. Returns an unsubscribe fn. */
-    onServer<E extends keyof ServerEvents<C>>(event: E, handler: (data: ServerData<ServerEvents<C>[E]>) => void): () => void;
     close(): Promise<void>;
 }
 /**
  * Create a server bound to a contract. Attach it to an `http.Server`, then call
- * {@link SocketServer.implement} with your handlers. `authenticate` resolves each
+ * {@link SuperLineServer.implement} with your handlers. `authenticate` resolves each
  * connection's `{ role, ctx }` at the upgrade.
  *
  * @param contract - the shared contract.
  * @param opts - server options; `authenticate` is required.
- * @returns the {@link SocketServer}.
- * @throws nothing directly; handler throws become a typed `SocketError` to the client.
+ * @returns the {@link SuperLineServer}.
+ * @throws nothing directly; handler throws become a typed `SuperLineError` to the client.
  *
  * @example
  * ```ts
- * const srv = createSocketServer(api, {
+ * const srv = createSuperLineServer(api, {
  *   server,
  *   authenticate: (req) => ({ role: 'user' as const, ctx: { id: '1' } }),
  * })
@@ -192,6 +324,6 @@ interface SocketServer<C extends Contract, A extends AuthResult<C>> {
  * })
  * ```
  */
-declare function createSocketServer<C extends Contract, A extends AuthResult<C>>(contract: C, opts: ServerOptions<C, A>): SocketServer<C, A>;
+declare function createSuperLineServer<C extends Contract, A extends AuthResult<C>>(contract: C, opts: SuperLineServerOptions<C, A>): SuperLineServer<C, A>;
 
-export { type AuthResult, Conn, type Handlers, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type ServerOptions, type SocketServer, createInMemoryAdapter, createSocketServer };
+export { type AuthResult, type Backpressure, type BusMeta, type ClusterView, Conn, type ConnTarget, type Handlers, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type SuperLineServer, type SuperLineServerOptions, type UserTarget, createInMemoryAdapter, createSuperLineServer };

package/dist/index.d.ts

@@ -1,7 +1,14 @@
 import { Server, IncomingMessage } from 'node:http';
-import { ServerMessageDef, Serializer, ServerFrame, EmitData, Adapter, Contract, RoleOf, SharedRequests, ServerInput, SharedEvents, Output, RoleRequests, Events, RoleTopics, SharedTopics, ServerEvents, ServerEmit, ServerData } from '@super-line/core';
+import { ServerMessageDef, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, SharedRequests, ServerInput, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, EventData } from '@super-line/core';
 import { WebSocket } from 'ws';
 
+/** Backpressure policy: what to do when a connection's send buffer grows too large. */
+interface Backpressure {
+    /** Buffer size (bytes) above which {@link Backpressure.onExceed} kicks in. */
+    maxBufferedBytes: number;
+    /** `'close'` (default) drops the connection with code 1013; `'drop'` skips the frame. */
+    onExceed?: 'close' | 'drop';
+}
 /**
  * A single client connection, passed to handlers as the third argument.
  *
@@ -10,23 +17,43 @@ import { WebSocket } from 'ws';
  * (use a per-user room instead). Generic over the events it may emit (scoped by
  * role), its `ctx`, and its `role`.
  */
-declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role extends string = string> {
+declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role extends string = string, Data = unknown> {
     /** The underlying `ws` socket. `conn.ws.terminate()` simulates a drop in tests. */
     readonly ws: WebSocket;
+    /** Server-assigned unique id for this connection (stable for its lifetime). */
+    readonly id: string;
     /** This connection's role (the literal resolved by `authenticate`). */
     readonly role: Role;
     /** The context `authenticate` returned for this connection. */
     readonly ctx: Ctx;
     private readonly serializer;
+    private readonly backpressure?;
+    /** Optional inspector tap: called with each `emit` so the server can mirror it to inspectors. */
+    private readonly onEmit?;
     /** Namespaced channels (rooms + topics) this connection belongs to. */
     readonly channels: Set<string>;
+    /** Mutable per-connection scratch state, typed per role by the contract's `data` schema. */
+    data: Data;
+    /** When this connection was accepted (`Date.now()` at the upgrade). */
+    readonly connectedAt: number;
+    /** When the server last sent a heartbeat ping to this connection (managed by the server). */
+    lastPingAt?: number;
+    /** When a heartbeat pong was last received — liveness signal (managed by the server). */
+    lastPongAt?: number;
+    /** Pings sent since the last pong; drives reaping (managed by the server). */
+    missedPongs: number;
     constructor(
     /** The underlying `ws` socket. `conn.ws.terminate()` simulates a drop in tests. */
     ws: WebSocket, 
+    /** Server-assigned unique id for this connection (stable for its lifetime). */
+    id: string, 
     /** This connection's role (the literal resolved by `authenticate`). */
     role: Role, 
     /** The context `authenticate` returned for this connection. */
-    ctx: Ctx, serializer: Serializer);
+    ctx: Ctx, serializer: Serializer, backpressure?: Backpressure | undefined, 
+    /** Optional inspector tap: called with each `emit` so the server can mirror it to inspectors. */
+    onEmit?: ((event: string, data: unknown) => void) | undefined);
+    private overBackpressure;
     /** Encode and send a frame (unicast, e.g. req/res). */
     send(frame: ServerFrame): void;
     /** Forward an already-encoded frame (fan-out path; encoded once at the source). */
@@ -40,9 +67,12 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
 /**
  * In-process pub/sub bus. Share one bus across multiple servers to simulate
  * multiple nodes in a test (each server gets its own adapter bound to the bus).
+ * The presence directory also lives here, so servers sharing a bus see the whole
+ * cluster (mirroring how Redis is shared in production).
  */
 declare class MemoryBus {
     private readonly channels;
+    readonly descriptors: Map<string, ConnDescriptor>;
     subscribe(channel: string, adapter: MemoryAdapter): void;
     unsubscribe(channel: string, adapter: MemoryAdapter): void;
     publish(channel: string, payload: string | Uint8Array): void;
@@ -50,6 +80,7 @@ declare class MemoryBus {
 declare class MemoryAdapter implements Adapter {
     private readonly bus;
     private handler?;
+    readonly presence: PresenceStore;
     constructor(bus: MemoryBus);
     subscribe(channel: string): void;
     unsubscribe(channel: string): void;
@@ -83,10 +114,10 @@ type CtxUnion<A> = A extends {
     ctx: infer X;
 } ? X : never;
 type RoleHandlers<C extends Contract, A, R extends RoleOf<C>> = {
-    [K in keyof RoleRequests<C, R>]: (input: ServerInput<RoleRequests<C, R>[K]>, ctx: CtxFor<A, R>, conn: Conn<Events<C, R>, CtxFor<A, R>, R>) => Awaitable<Output<RoleRequests<C, R>[K]>>;
+    [K in keyof RoleRequests<C, R>]: (input: ServerInput<RoleRequests<C, R>[K]>, ctx: CtxFor<A, R>, conn: Conn<Events<C, R>, CtxFor<A, R>, R, DataOf<C, R>>) => Awaitable<Output<RoleRequests<C, R>[K]>>;
 };
 type SharedHandlers<C extends Contract, A> = {
-    [K in keyof SharedRequests<C>]: (input: ServerInput<SharedRequests<C>[K]>, ctx: CtxUnion<A>, conn: Conn<SharedEvents<C>, CtxUnion<A>, RoleOf<C>>) => Awaitable<Output<SharedRequests<C>[K]>>;
+    [K in keyof SharedRequests<C>]: (input: ServerInput<SharedRequests<C>[K]>, ctx: CtxUnion<A>, conn: Conn<SharedEvents<C>, CtxUnion<A>, RoleOf<C>, AnyData<C>>) => Awaitable<Output<SharedRequests<C>[K]>>;
 };
 /**
  * The handler map passed to `implement`: one block per role plus an optional
@@ -100,12 +131,17 @@ type Handlers<C extends Contract, A> = ([keyof SharedRequests<C>] extends [never
 };
 /** Context passed to middleware and lifecycle hooks about the current operation. */
 interface MiddlewareInfo {
-    /** Whether this is a request or a topic subscribe. */
-    kind: 'request' | 'subscribe';
-    /** The request/topic name. */
+    /** Whether this is a request, a topic subscribe, or a bus event delivery. */
+    kind: 'request' | 'subscribe' | 'event';
+    /** The request/topic/event name. */
     name: string;
-    /** The connection the operation is on (`conn.role` available). */
-    conn: Conn;
+    /** The connection the operation is on, if any (`conn.role` available). Absent for bus events. */
+    conn?: Conn;
+}
+/** Metadata passed to a {@link SuperLineServer.subscribe} callback alongside the event payload. */
+interface BusMeta {
+    /** The node that published the event. Equals `srv.nodeId` for a same-node publish (local echo). */
+    from: string;
 }
 /**
  * Flat middleware run before request/subscribe handlers. Call `next()` to proceed,
@@ -125,14 +161,64 @@ interface Room<C extends Contract> {
     broadcast<E extends keyof SharedEvents<C>>(event: E, data: EmitData<SharedEvents<C>[E]>): void;
     /** Member count **on the current node** (membership is node-local). */
     readonly size: number;
+    /** Snapshot of this room's members **on the current node**. */
+    readonly connections: Conn[];
+}
+/** Synchronous, node-local introspection of the current server process. */
+interface LocalView {
+    /** Snapshot of all connections accepted on this node. */
+    readonly connections: Conn[];
+    /** Names of rooms with at least one member on this node. */
+    readonly rooms: string[];
+    /** Names of topics with at least one subscriber on this node. */
+    readonly topics: string[];
+}
+/**
+ * Asynchronous, cluster-wide introspection backed by the adapter's presence
+ * directory. Methods reject if the configured adapter has no presence support.
+ */
+interface ClusterView {
+    /** Every live connection across the cluster. */
+    connections(): Promise<ConnDescriptor[]>;
+    /** Total live connection count across the cluster. */
+    count(): Promise<number>;
+    /** Connections for a given user key (the `identify` hook). */
+    byUser(userId: string): Promise<ConnDescriptor[]>;
+    /** Connections that are members of `room`, across nodes. */
+    room(name: string): Promise<ConnDescriptor[]>;
+    /** Per-node aggregates (the other nodes and their counts). */
+    topology(): Promise<NodeStat[]>;
+}
+/** A single targeted connection, reachable on whatever node holds it. */
+interface ConnTarget<C extends Contract> {
+    /** Push a shared event to this connection (cross-node). */
+    emit<E extends keyof SharedEvents<C>>(event: E, data: EmitData<SharedEvents<C>[E]>): void;
+    /**
+     * Send a shared server→client request and await the client's typed reply
+     * (cross-node). Rejects with a `TIMEOUT` `SuperLineError` if no live node owns
+     * the connection or the client doesn't answer in time.
+     */
+    request<M extends keyof SharedServerRequests<C>>(name: M, input: ClientInput<SharedServerRequests<C>[M]>, opts?: {
+        timeout?: number;
+        signal?: AbortSignal;
+    }): Promise<Output<SharedServerRequests<C>[M]>>;
+    /** Close this connection (cross-node kick). */
+    close(): void;
+}
+/** All of a user's connections (0..N devices), reachable across nodes. */
+interface UserTarget<C extends Contract> {
+    /** Push a shared event to every one of the user's connections (cross-node). */
+    emit<E extends keyof SharedEvents<C>>(event: E, data: EmitData<SharedEvents<C>[E]>): void;
+    /** Disconnect every one of the user's connections (cross-node). */
+    disconnect(): void;
 }
 /** Lens for role-scoped server sends, returned by `srv.forRole(role)`. */
 interface RoleLens<C extends Contract, R extends RoleOf<C>> {
     /** Publish to a topic in role `R`'s surface (reaches that role's subscribers). */
     publish<T extends keyof RoleTopics<C, R>>(topic: T, data: EmitData<RoleTopics<C, R>[T]>): void;
 }
-/** Options for {@link createSocketServer}. */
-interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
+/** Options for {@link createSuperLineServer}. */
+interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>> {
     /** The `http.Server` to attach to (compose with Express/Fastify/Hono). */
     server?: Server;
     /** Wire serializer; MUST match the client. Defaults to `jsonSerializer`. */
@@ -141,12 +227,41 @@ interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
     adapter?: Adapter;
     /** Only handle upgrades for this pathname; others are left untouched. */
     path?: string;
+    /**
+     * Friendly name for this node, surfaced in `srv.nodeName`, the cluster descriptor, and the
+     * Control Center topology. Defaults to `SUPER_LINE_NODE_NAME` or a short slice of `nodeId`.
+     */
+    nodeName?: string;
     /** Runs at the HTTP upgrade. Return { role, ctx }, or throw to reject with 401. */
     authenticate: (req: IncomingMessage) => Awaitable<A>;
+    /** Stable user key for a connection (powers `cluster.byUser`, `isOnline`, and `toUser`). */
+    identify?: (conn: Conn) => string | undefined;
+    /** Extra fields merged into the connection's cluster descriptor (e.g. `{ plan }`). `ctx` is never auto-serialized. */
+    describeConn?: (conn: Conn) => Record<string, unknown>;
     /** Runs on each client subscribe. Return false or throw to deny. */
     authorizeSubscribe?: (topic: string, ctx: CtxUnion<A>, conn: Conn) => Awaitable<boolean | void>;
     /** Middleware chain run before req/subscribe handlers (rate-limit, authz, logging, metrics). */
     use?: Middleware<A>[];
+    /**
+     * Heartbeat: one timer pings every connection each `interval` ms (updating
+     * `conn.lastPingAt`/`lastPongAt`). Set `maxMissed` to terminate a connection
+     * that misses that many consecutive pongs. `false` disables it.
+     * Defaults to `{ interval: 30_000 }` (no reaping).
+     */
+    heartbeat?: {
+        interval?: number;
+        maxMissed?: number;
+    } | false;
+    /** Guard against slow consumers: when a connection's send buffer exceeds the limit, close or drop. */
+    backpressure?: Backpressure;
+    /**
+     * Read-only Control Center inspector channel, reached via the WS subprotocol
+     * `superline.inspector.v1`. Connections on it bypass `authenticate` and are kept out of
+     * presence, the heartbeat, and `local`/`cluster` results. **Default off; dev / trusted-network only.**
+     */
+    inspector?: boolean | {
+        redact?: string[];
+    };
     /** Called once per accepted connection. */
     onConnection?: (conn: Conn, ctx: CtxUnion<A>) => void;
     /** Called when a connection closes, with the WebSocket close `code`. */
@@ -154,35 +269,52 @@ interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
     /** Called for any error thrown in middleware/handlers (after the client is replied to). */
     onError?: (error: unknown, info: MiddlewareInfo) => void;
 }
-/** A running super-line server, returned by {@link createSocketServer}. */
-interface SocketServer<C extends Contract, A extends AuthResult<C>> {
+/** A running super-line server, returned by {@link createSuperLineServer}. */
+interface SuperLineServer<C extends Contract, A extends AuthResult<C>> {
+    /** This node's stable id (unique per server process). */
+    readonly nodeId: string;
+    /** This node's friendly name (from `nodeName`/`SUPER_LINE_NODE_NAME`, else a short `nodeId` slice). */
+    readonly nodeName: string;
+    /** Synchronous, node-local introspection (connections, rooms, topics on this process). */
+    readonly local: LocalView;
+    /** Asynchronous, cluster-wide introspection backed by the adapter's presence directory. */
+    readonly cluster: ClusterView;
+    /** Whether a user (by `identify` key) has at least one live connection anywhere. */
+    isOnline(userId: string): Promise<boolean>;
+    /** Target a single connection by id, on whatever node holds it (cross-node emit/close). */
+    toConn(id: string): ConnTarget<C>;
+    /** Target all of a user's connections (by `identify` key) across nodes (emit/disconnect). */
+    toUser(userId: string): UserTarget<C>;
     /** Register handlers for shared + per-role requests (chainable). */
-    implement(handlers: Handlers<C, A>): SocketServer<C, A>;
+    implement(handlers: Handlers<C, A>): SuperLineServer<C, A>;
     /** Mixed-role connection group; broadcast() sends a shared contract event to members. */
     room(name: string): Room<C>;
     /** Publish a SHARED topic to all subscribers (server-only publish). */
     publish<T extends keyof SharedTopics<C>>(topic: T, data: EmitData<SharedTopics<C>[T]>): void;
+    /**
+     * Subscribe SERVER-side to a shared topic, cluster-wide. The callback fires for a
+     * publish from any node — including this one (local echo, delivered in-process with
+     * no round-trip). `meta.from` is the publishing node; self-exclude with
+     * `if (meta.from === srv.nodeId) return`. Returns an unsubscribe fn.
+     */
+    subscribe<T extends keyof SharedTopics<C>>(topic: T, handler: (data: EventData<SharedTopics<C>[T]>, meta: BusMeta) => void): () => void;
     /** Lens for role-scoped sends, e.g. forRole('user').publish('feed', data). */
     forRole<R extends RoleOf<C>>(role: R): RoleLens<C, R>;
-    /** Broadcast a typed event to all OTHER server nodes (at-most-once, excludes self). */
-    emitServer<E extends keyof ServerEvents<C>>(event: E, data: ServerEmit<ServerEvents<C>[E]>): void;
-    /** Listen for inter-server events from other nodes. Returns an unsubscribe fn. */
-    onServer<E extends keyof ServerEvents<C>>(event: E, handler: (data: ServerData<ServerEvents<C>[E]>) => void): () => void;
     close(): Promise<void>;
 }
 /**
  * Create a server bound to a contract. Attach it to an `http.Server`, then call
- * {@link SocketServer.implement} with your handlers. `authenticate` resolves each
+ * {@link SuperLineServer.implement} with your handlers. `authenticate` resolves each
  * connection's `{ role, ctx }` at the upgrade.
  *
  * @param contract - the shared contract.
  * @param opts - server options; `authenticate` is required.
- * @returns the {@link SocketServer}.
- * @throws nothing directly; handler throws become a typed `SocketError` to the client.
+ * @returns the {@link SuperLineServer}.
+ * @throws nothing directly; handler throws become a typed `SuperLineError` to the client.
  *
  * @example
  * ```ts
- * const srv = createSocketServer(api, {
+ * const srv = createSuperLineServer(api, {
  *   server,
  *   authenticate: (req) => ({ role: 'user' as const, ctx: { id: '1' } }),
  * })
@@ -192,6 +324,6 @@ interface SocketServer<C extends Contract, A extends AuthResult<C>> {
  * })
  * ```
  */
-declare function createSocketServer<C extends Contract, A extends AuthResult<C>>(contract: C, opts: ServerOptions<C, A>): SocketServer<C, A>;
+declare function createSuperLineServer<C extends Contract, A extends AuthResult<C>>(contract: C, opts: SuperLineServerOptions<C, A>): SuperLineServer<C, A>;
 
-export { type AuthResult, Conn, type Handlers, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type ServerOptions, type SocketServer, createInMemoryAdapter, createSocketServer };
+export { type AuthResult, type Backpressure, type BusMeta, type ClusterView, Conn, type ConnTarget, type Handlers, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type SuperLineServer, type SuperLineServerOptions, type UserTarget, createInMemoryAdapter, createSuperLineServer };