@super-line/server 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -1,25 +1,16 @@
-import { Server, IncomingMessage } from 'node:http';
-import { ServerMessageDef, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, SharedRequests, ServerInput, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, ServerEvents, ServerEmit, ServerData } from '@super-line/core';
-import { WebSocket } from 'ws';
+import { ServerMessageDef, RawConn, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, SharedRequests, ServerInput, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, EventData, ServerTransport, Handshake } from '@super-line/core';
 
-/** 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.
  *
- * Node-local: `conn` objects live on the node that accepted the upgrade, so don't
+ * Node-local: `conn` objects live on the node that accepted the connection, so don't
  * stash one to reach a user later — cross-node delivery goes through the Adapter
  * (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, Data = unknown> {
-    /** The underlying `ws` socket. `conn.ws.terminate()` simulates a drop in tests. */
-    readonly ws: WebSocket;
+    /** The underlying transport connection. `conn.terminate()` simulates a drop in tests. */
+    readonly raw: RawConn;
     /** Server-assigned unique id for this connection (stable for its lifetime). */
     readonly id: string;
     /** This connection's role (the literal resolved by `authenticate`). */
@@ -27,12 +18,15 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
     /** 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). */
+    /** The client↔server transport (wire) this connection was accepted on (set by the server at accept). */
+    transport?: string;
+    /** When this connection was accepted (`Date.now()`). */
     readonly connectedAt: number;
     /** When the server last sent a heartbeat ping to this connection (managed by the server). */
     lastPingAt?: number;
@@ -41,23 +35,26 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
     /** 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, 
+    /** The underlying transport connection. `conn.terminate()` simulates a drop in tests. */
+    raw: RawConn, 
     /** 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, backpressure?: Backpressure | undefined);
-    private overBackpressure;
+    ctx: Ctx, serializer: Serializer, 
+    /** Optional inspector tap: called with each `emit` so the server can mirror it to inspectors. */
+    onEmit?: ((event: string, data: unknown) => void) | undefined);
     /** 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). */
     sendRaw(payload: string | Uint8Array): void;
     /** Push an event to THIS connection (node-local). Scoped to the role's events. */
     emit<E extends keyof Ev>(event: E, data: EmitData<Ev[E]>): void;
-    /** Close the underlying socket. */
+    /** Graceful close of the underlying transport connection. */
     close(): void;
+    /** Hard close with no handshake — used by heartbeat reaping. */
+    terminate(): void;
 }
 
 /**
@@ -127,12 +124,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,
@@ -186,7 +188,7 @@ interface ConnTarget<C extends Contract> {
     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` `SocketError` if no live node owns
+     * (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?: {
@@ -208,18 +210,21 @@ 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>> {
-    /** The `http.Server` to attach to (compose with Express/Fastify/Hono). */
-    server?: Server;
+/** Options for {@link createSuperLineServer}. */
+interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>> {
+    /** Client↔server transports to accept connections on (e.g. `webSocketServerTransport({ server })`). */
+    transports: ServerTransport[];
     /** Wire serializer; MUST match the client. Defaults to `jsonSerializer`. */
     serializer?: Serializer;
     /** Cross-node fan-out adapter. Defaults to a per-server in-memory adapter. */
     adapter?: Adapter;
-    /** Only handle upgrades for this pathname; others are left untouched. */
-    path?: string;
-    /** Runs at the HTTP upgrade. Return { role, ctx }, or throw to reject with 401. */
-    authenticate: (req: IncomingMessage) => Awaitable<A>;
+    /**
+     * 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;
+    /** Authenticate a connection from its normalized {@link Handshake}. Return { role, ctx }, or throw to reject. */
+    authenticate: (handshake: Handshake) => 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. */
@@ -238,8 +243,14 @@ interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
         interval?: number;
         maxMissed?: number;
     } | false;
-    /** Guard against slow consumers: when a connection's send buffer exceeds the limit, close or drop. */
-    backpressure?: Backpressure;
+    /**
+     * Enable the read-only Control Center inspector: emit `msg.*` telemetry and accept inspector
+     * clients. The WS transport must also be created with `inspector: true` to negotiate the
+     * `superline.inspector.v1` subprotocol. **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`. */
@@ -247,10 +258,12 @@ 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. */
@@ -262,34 +275,37 @@ interface SocketServer<C extends Contract, A extends AuthResult<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, {
- *   server,
- *   authenticate: (req) => ({ role: 'user' as const, ctx: { id: '1' } }),
+ * const srv = createSuperLineServer(api, {
+ *   transports: [webSocketServerTransport({ server })],
+ *   authenticate: (h) => ({ role: 'user' as const, ctx: { id: '1' } }),
  * })
  * srv.implement({
  *   shared: { join: async ({ room }, _ctx, conn) => { srv.room(room).add(conn); return { ok: true } } },
@@ -297,6 +313,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, type Backpressure, type ClusterView, Conn, type ConnTarget, type Handlers, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type ServerOptions, type SocketServer, type UserTarget, createInMemoryAdapter, createSocketServer };
+export { type AuthResult, 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,25 +1,16 @@
-import { Server, IncomingMessage } from 'node:http';
-import { ServerMessageDef, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, SharedRequests, ServerInput, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, ServerEvents, ServerEmit, ServerData } from '@super-line/core';
-import { WebSocket } from 'ws';
+import { ServerMessageDef, RawConn, Serializer, ServerFrame, EmitData, ConnDescriptor, Adapter, PresenceStore, Contract, RoleOf, NodeStat, SharedEvents, SharedServerRequests, ClientInput, Output, SharedRequests, ServerInput, AnyData, RoleRequests, Events, DataOf, RoleTopics, SharedTopics, EventData, ServerTransport, Handshake } from '@super-line/core';
 
-/** 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.
  *
- * Node-local: `conn` objects live on the node that accepted the upgrade, so don't
+ * Node-local: `conn` objects live on the node that accepted the connection, so don't
  * stash one to reach a user later — cross-node delivery goes through the Adapter
  * (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, Data = unknown> {
-    /** The underlying `ws` socket. `conn.ws.terminate()` simulates a drop in tests. */
-    readonly ws: WebSocket;
+    /** The underlying transport connection. `conn.terminate()` simulates a drop in tests. */
+    readonly raw: RawConn;
     /** Server-assigned unique id for this connection (stable for its lifetime). */
     readonly id: string;
     /** This connection's role (the literal resolved by `authenticate`). */
@@ -27,12 +18,15 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
     /** 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). */
+    /** The client↔server transport (wire) this connection was accepted on (set by the server at accept). */
+    transport?: string;
+    /** When this connection was accepted (`Date.now()`). */
     readonly connectedAt: number;
     /** When the server last sent a heartbeat ping to this connection (managed by the server). */
     lastPingAt?: number;
@@ -41,23 +35,26 @@ declare class Conn<Ev = Record<string, ServerMessageDef>, Ctx = unknown, Role ex
     /** 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, 
+    /** The underlying transport connection. `conn.terminate()` simulates a drop in tests. */
+    raw: RawConn, 
     /** 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, backpressure?: Backpressure | undefined);
-    private overBackpressure;
+    ctx: Ctx, serializer: Serializer, 
+    /** Optional inspector tap: called with each `emit` so the server can mirror it to inspectors. */
+    onEmit?: ((event: string, data: unknown) => void) | undefined);
     /** 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). */
     sendRaw(payload: string | Uint8Array): void;
     /** Push an event to THIS connection (node-local). Scoped to the role's events. */
     emit<E extends keyof Ev>(event: E, data: EmitData<Ev[E]>): void;
-    /** Close the underlying socket. */
+    /** Graceful close of the underlying transport connection. */
     close(): void;
+    /** Hard close with no handshake — used by heartbeat reaping. */
+    terminate(): void;
 }
 
 /**
@@ -127,12 +124,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,
@@ -186,7 +188,7 @@ interface ConnTarget<C extends Contract> {
     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` `SocketError` if no live node owns
+     * (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?: {
@@ -208,18 +210,21 @@ 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>> {
-    /** The `http.Server` to attach to (compose with Express/Fastify/Hono). */
-    server?: Server;
+/** Options for {@link createSuperLineServer}. */
+interface SuperLineServerOptions<C extends Contract, A extends AuthResult<C>> {
+    /** Client↔server transports to accept connections on (e.g. `webSocketServerTransport({ server })`). */
+    transports: ServerTransport[];
     /** Wire serializer; MUST match the client. Defaults to `jsonSerializer`. */
     serializer?: Serializer;
     /** Cross-node fan-out adapter. Defaults to a per-server in-memory adapter. */
     adapter?: Adapter;
-    /** Only handle upgrades for this pathname; others are left untouched. */
-    path?: string;
-    /** Runs at the HTTP upgrade. Return { role, ctx }, or throw to reject with 401. */
-    authenticate: (req: IncomingMessage) => Awaitable<A>;
+    /**
+     * 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;
+    /** Authenticate a connection from its normalized {@link Handshake}. Return { role, ctx }, or throw to reject. */
+    authenticate: (handshake: Handshake) => 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. */
@@ -238,8 +243,14 @@ interface ServerOptions<C extends Contract, A extends AuthResult<C>> {
         interval?: number;
         maxMissed?: number;
     } | false;
-    /** Guard against slow consumers: when a connection's send buffer exceeds the limit, close or drop. */
-    backpressure?: Backpressure;
+    /**
+     * Enable the read-only Control Center inspector: emit `msg.*` telemetry and accept inspector
+     * clients. The WS transport must also be created with `inspector: true` to negotiate the
+     * `superline.inspector.v1` subprotocol. **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`. */
@@ -247,10 +258,12 @@ 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. */
@@ -262,34 +275,37 @@ interface SocketServer<C extends Contract, A extends AuthResult<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, {
- *   server,
- *   authenticate: (req) => ({ role: 'user' as const, ctx: { id: '1' } }),
+ * const srv = createSuperLineServer(api, {
+ *   transports: [webSocketServerTransport({ server })],
+ *   authenticate: (h) => ({ role: 'user' as const, ctx: { id: '1' } }),
  * })
  * srv.implement({
  *   shared: { join: async ({ room }, _ctx, conn) => { srv.room(room).add(conn); return { ok: true } } },
@@ -297,6 +313,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, type Backpressure, type ClusterView, Conn, type ConnTarget, type Handlers, type LocalView, MemoryBus, type Middleware, type MiddlewareInfo, type RoleLens, type Room, type ServerOptions, type SocketServer, type UserTarget, createInMemoryAdapter, createSocketServer };
+export { type AuthResult, 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 };