@pellux/goodvibes-transport-realtime 0.33.36 → 0.33.38

package/dist/index.d.ts

@@ -2,5 +2,6 @@ export type { DomainEventConnector, DomainEvents, RemoteDomainEventsOptions, Ser
 export { createRemoteDomainEvents, forSession } from './domain-events.js';
 export type { RemoteRuntimeEvents, RemoteRuntimeEventsOptions, SerializedRuntimeEnvelope } from './runtime-events.js';
 export { buildEventSourceUrl, buildWebSocketUrl, createEventSourceConnector, createRemoteRuntimeEvents, createWebSocketConnector, DEFAULT_WS_MAX_ATTEMPTS, forSessionRuntime, WebSocketTransportError, } from './runtime-events.js';
-export type { AuthTokenSource, RuntimeEventConnectorOptions } from './runtime-events.js';
+export type { AuthTokenSource, BackpressureInfo, ConnectionState, ConnectorTransportEvent, ReconnectAttemptInfo, RuntimeEventConnectorOptions, } from './runtime-events.js';
+export { createWebSocketRemoteError } from './runtime-events.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,oBAAoB,EACpB,YAAY,EACZ,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,wBAAwB,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC1E,YAAY,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AACtH,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,uBAAuB,EACvB,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,eAAe,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,oBAAoB,EACpB,YAAY,EACZ,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,wBAAwB,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC1E,YAAY,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AACtH,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,uBAAuB,EACvB,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,uBAAuB,EACvB,oBAAoB,EACpB,4BAA4B,GAC7B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,2 +1,3 @@
 export { createRemoteDomainEvents, forSession } from './domain-events.js';
 export { buildEventSourceUrl, buildWebSocketUrl, createEventSourceConnector, createRemoteRuntimeEvents, createWebSocketConnector, DEFAULT_WS_MAX_ATTEMPTS, forSessionRuntime, WebSocketTransportError, } from './runtime-events.js';
+export { createWebSocketRemoteError } from './runtime-events.js';

package/dist/runtime-events.d.ts

@@ -3,6 +3,34 @@ import { GoodVibesSdkError } from '@pellux/goodvibes-errors';
 import { type AuthTokenResolver, type StreamReconnectPolicy } from '@pellux/goodvibes-transport-http';
 import { type TransportObserver } from '@pellux/goodvibes-transport-core';
 import { type DomainEventConnector, type DomainEvents, type SerializedEventEnvelope } from './domain-events.js';
+/**
+ * Typed transport observability events emitted by the WebSocket connector.
+ *
+ * A structural subset of the SDK-level `TransportEvent` union — the SDK
+ * (`@pellux/goodvibes-sdk`) extends this with additional server-side event
+ * types. Client code that holds a reference to the full `TransportEvent` union
+ * can use this type without narrowing since the shapes are structurally
+ * compatible.
+ */
+export type ConnectorTransportEvent = {
+    type: 'TRANSPORT_CONNECTION_STATE';
+    transportId: string;
+    state: 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'failed';
+} | {
+    type: 'TRANSPORT_RECONNECT_ATTEMPT';
+    transportId: string;
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    reason: string;
+} | {
+    type: 'TRANSPORT_BACKPRESSURE';
+    transportId: string;
+    droppedCount: number;
+    queueLength: number;
+    queueBytes: number;
+    reason: 'message_too_large' | 'queue_full';
+};
 export type SerializedRuntimeEnvelope<TEvent extends RuntimeEventRecord = RuntimeEventRecord> = SerializedEventEnvelope<TEvent>;
 export type RemoteRuntimeEvents<TEvent extends RuntimeEventRecord = RuntimeEventRecord> = DomainEvents<RuntimeEventDomain, TEvent>;
 export interface RemoteRuntimeEventsOptions {
@@ -36,11 +64,66 @@ export interface RemoteRuntimeEventsOptions {
  * });
  */
 export { forSession as forSessionRuntime } from './domain-events.js';
+/**
+ * Connection state for a realtime transport.
+ *
+ * - `connecting`    — the socket is being established (or re-connecting after a clean stop).
+ * - `connected`     — the connection is authenticated and open; outbound messages may be sent.
+ * - `reconnecting`  — the connection was lost and the connector is waiting before the next attempt.
+ * - `disconnected`  — the connector was stopped cleanly (no further reconnects will occur).
+ * - `failed`        — the maximum reconnect attempts were exhausted; the connection is permanently closed.
+ */
+export type ConnectionState = 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'failed';
+/** Metadata emitted on every reconnect attempt. */
+export interface ReconnectAttemptInfo {
+    /** 1-based reconnect attempt index. */
+    readonly attempt: number;
+    /** Maximum attempts configured; `Infinity` means unlimited. */
+    readonly maxAttempts: number;
+    /** Milliseconds the connector will wait before the attempt. */
+    readonly delayMs: number;
+    /** Human-readable reason for the reconnect (e.g. the error message or WS close code). */
+    readonly reason: string;
+}
+/** Metadata emitted when the outbound queue saturates. */
+export interface BackpressureInfo {
+    /** Number of messages dropped since the last successful flush. */
+    readonly droppedCount: number;
+    /** Current number of messages in the outbound queue. */
+    readonly queueLength: number;
+    /** Current byte footprint of the outbound queue. */
+    readonly queueBytes: number;
+    /** The overflow reason: 'message_too_large' or 'queue_full'. */
+    readonly reason: 'message_too_large' | 'queue_full';
+}
 export interface RuntimeEventConnectorOptions {
     readonly reconnect?: StreamReconnectPolicy | undefined;
     readonly onError?: ((error: unknown) => void) | undefined;
     readonly onOpen?: (() => void) | undefined;
+    /** @deprecated Use `onReconnectAttempt` for richer metadata. This callback is still fired for backward compatibility. */
     readonly onReconnect?: ((attempt: number, delayMs: number) => void) | undefined;
+    /** Called on every reconnect attempt with structured metadata. */
+    readonly onReconnectAttempt?: ((info: ReconnectAttemptInfo) => void) | undefined;
+    /** Called when the connection state changes. Subscribe to drive connection-state UI badges. */
+    readonly onConnectionStateChange?: ((state: ConnectionState) => void) | undefined;
+    /**
+     * Called when the outbound queue saturates or a single message is too large to queue.
+     *
+     * **Throttling:** callbacks are emitted on the 1st overflow and every 10th overflow
+     * thereafter to avoid flooding callers during sustained disconnections. `droppedCount`
+     * in {@link BackpressureInfo} is always the cumulative total — use it as the source of
+     * truth for exact drop counts; do not count callback invocations.
+     */
+    readonly onBackpressure?: ((info: BackpressureInfo) => void) | undefined;
+    /**
+     * Called when a typed {@link TransportEvent} is dispatched by the connector.
+     *
+     * Fires for `TRANSPORT_CONNECTION_STATE`, `TRANSPORT_RECONNECT_ATTEMPT`, and
+     * `TRANSPORT_BACKPRESSURE` events in addition to the dedicated callbacks above.
+     * Subscribe to this to receive a single unified stream of observability events
+     * suitable for forwarding to an event bus or UI state store.
+     */
+    readonly onTransportEvent?: ((event: ConnectorTransportEvent) => void) | undefined;
     readonly observer?: TransportObserver | undefined;
     /**
      * Called once the WebSocket connector is set up, providing an `emitLocal`
@@ -52,6 +135,11 @@ export interface RuntimeEventConnectorOptions {
 export type AuthTokenSource = string | null | undefined | AuthTokenResolver;
 /** Default max reconnect attempts for WebSocket connections (finite to prevent infinite auth loops). */
 export declare const DEFAULT_WS_MAX_ATTEMPTS = 10;
+export declare function createWebSocketRemoteError(fallbackMessage: string, body: unknown, options?: {
+    readonly code?: string;
+    readonly hint?: string;
+    readonly cause?: unknown;
+}): WebSocketTransportError;
 export declare class WebSocketTransportError extends GoodVibesSdkError {
     /**
      * WebSocket runtime-event transport error.
@@ -72,6 +160,15 @@ export declare class WebSocketTransportError extends GoodVibesSdkError {
         readonly cause?: unknown;
         readonly hint?: string;
         readonly code: string;
+        /** Defaults to `'network'`. Override when the server sends a structured category (e.g. `'rate_limit'`). */
+        readonly category?: import('@pellux/goodvibes-errors').ErrorCategory | undefined;
+        /** Defaults to `true`. Override to `false` for unrecoverable structured errors. */
+        readonly recoverable?: boolean | undefined;
+        readonly status?: number | undefined;
+        readonly requestId?: string | undefined;
+        readonly provider?: string | undefined;
+        readonly operation?: string | undefined;
+        readonly phase?: string | undefined;
     });
 }
 export declare function createRemoteRuntimeEvents<TEvent extends RuntimeEventRecord = RuntimeEventRecord>(connect: DomainEventConnector<RuntimeEventDomain, TEvent>, options?: RemoteRuntimeEventsOptions): RemoteRuntimeEvents<TEvent>;

package/dist/runtime-events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-events.d.ts","sourceRoot":"","sources":["../src/runtime-events.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtime-events.d.ts","sourceRoot":"","sources":["../src/runtime-events.ts"],"names":[],"mappings":"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"}

package/dist/runtime-events.js

@@ -1,5 +1,5 @@
 import { RUNTIME_EVENT_DOMAINS, TypedSerializedEventEnvelopeSchema, } from '@pellux/goodvibes-contracts';
-import { ConfigurationError, GoodVibesSdkError } from '@pellux/goodvibes-errors';
+import { ConfigurationError, GoodVibesSdkError, isStructuredDaemonErrorBody, } from '@pellux/goodvibes-errors';
 import { normalizeAuthToken, openRawServerSentEventStream as openServerSentEventStream, normalizeStreamReconnectPolicy, getStreamReconnectDelay, } from '@pellux/goodvibes-transport-http';
 import { buildUrl, normalizeBaseUrl } from '@pellux/goodvibes-transport-http';
 import { describeUnknownTransportError, injectTraceparentAsync, invokeTransportObserver, transportErrorFromUnknown, } from '@pellux/goodvibes-transport-core';
@@ -48,6 +48,86 @@ function getSocketOpenState(WebSocketImpl) {
 function isSocketOpen(socket, WebSocketImpl) {
     return socket.readyState === getSocketOpenState(WebSocketImpl);
 }
+/**
+ * Creates a {@link WebSocketTransportError} from a raw server-sent payload body,
+ * unpacking a {@link StructuredDaemonErrorBody} when present — matching the
+ * envelope parity that `createHttpStatusError` provides for HTTP errors.
+ *
+ * When the server sends a structured `{ error, code, category, recoverable, … }` body
+ * inside a WS message, consumers receive the same richly-typed envelope as HTTP callers.
+ * Unstructured or non-object bodies fall back to the provided `fallbackMessage`.
+ *
+ * @param fallbackMessage - Used when `body` is not a structured daemon error.
+ * @param body - The raw body parsed from the server frame (may be any shape).
+ * @param options - Optional overrides for `code`, `hint`, and `cause`.
+ */
+/**
+ * Helper that builds a {@link WebSocketTransportError} options bag without
+ * assigning `undefined` to optional keys, satisfying `exactOptionalPropertyTypes`.
+ */
+function buildWsErrorOpts(code, overrides = {}) {
+    const opts = { code };
+    if (overrides.hint !== undefined)
+        opts['hint'] = overrides.hint;
+    if (overrides.cause !== undefined)
+        opts['cause'] = overrides.cause;
+    if (overrides.category !== undefined)
+        opts['category'] = overrides.category;
+    if (overrides.recoverable !== undefined)
+        opts['recoverable'] = overrides.recoverable;
+    if (overrides.status !== undefined)
+        opts['status'] = overrides.status;
+    if (overrides.requestId !== undefined)
+        opts['requestId'] = overrides.requestId;
+    if (overrides.provider !== undefined)
+        opts['provider'] = overrides.provider;
+    if (overrides.operation !== undefined)
+        opts['operation'] = overrides.operation;
+    if (overrides.phase !== undefined)
+        opts['phase'] = overrides.phase;
+    return opts;
+}
+export function createWebSocketRemoteError(fallbackMessage, body, options = {}) {
+    if (isStructuredDaemonErrorBody(body)) {
+        const overrides = {};
+        const effectiveHint = body.hint ?? options.hint;
+        if (effectiveHint !== undefined)
+            overrides.hint = effectiveHint;
+        if (options.cause !== undefined)
+            overrides.cause = options.cause;
+        if (body.category !== undefined)
+            overrides.category = body.category;
+        if (body.recoverable !== undefined)
+            overrides.recoverable = body.recoverable;
+        if (body.status !== undefined)
+            overrides.status = body.status;
+        if (body.requestId !== undefined)
+            overrides.requestId = body.requestId;
+        if (body.provider !== undefined)
+            overrides.provider = body.provider;
+        if (body.operation !== undefined)
+            overrides.operation = body.operation;
+        if (body.phase !== undefined)
+            overrides.phase = body.phase;
+        // Use the caller-supplied code (or 'WS_REMOTE_ERROR') as the canonical transport code.
+        // The server's body.code is not used as the WebSocketTransportError code because
+        // Symbol.hasInstance enforces a canonical-code allowlist; arbitrary server codes
+        // would break instanceof checks. The body message and metadata are still preserved.
+        const code = options.code ?? 'WS_REMOTE_ERROR';
+        return new WebSocketTransportError(body.error, buildWsErrorOpts(code, overrides));
+    }
+    const message = typeof body === 'string' && body.trim()
+        ? body.trim()
+        : fallbackMessage;
+    const overrides = {};
+    if (options.hint !== undefined)
+        overrides.hint = options.hint;
+    if (options.cause !== undefined)
+        overrides.cause = options.cause;
+    else if (body !== null && body !== undefined)
+        overrides.cause = body;
+    return new WebSocketTransportError(message, buildWsErrorOpts(options.code ?? 'WS_REMOTE_ERROR', overrides));
+}
 export class WebSocketTransportError extends GoodVibesSdkError {
     /**
      * WebSocket runtime-event transport error.
@@ -87,14 +167,23 @@ export class WebSocketTransportError extends GoodVibesSdkError {
             && CANONICAL_WS_CODES.has(String(value.code));
     }
     // Use one of: WS_CLOSE_ABNORMAL, WS_EVENT_ERROR, WS_QUEUE_OVERFLOW, WS_REMOTE_ERROR, WS_FRAME_TOO_LARGE.
+    //
+    // Extended options mirror the HttpStatusError / createHttpStatusError envelope so that
+    // structured daemon error bodies received over WebSocket produce the same richly-typed
+    // error as their HTTP equivalents. Fields omitted default to transport-appropriate values.
     constructor(message, options) {
         super(message, {
             code: options.code,
-            category: 'network',
+            category: options.category ?? 'network',
             source: 'transport',
-            recoverable: true,
+            recoverable: options.recoverable ?? true,
             hint: options.hint,
             cause: options.cause,
+            status: options.status,
+            requestId: options.requestId,
+            provider: options.provider,
+            operation: options.operation,
+            phase: options.phase,
         });
         this.name = 'WebSocketTransportError';
     }
@@ -216,6 +305,23 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
         let hasReceivedMessage = false;
         let socket = null;
         let reconnectTimer = null;
+        // Track last emitted connection state to avoid duplicate emissions.
+        let lastConnectionState = null;
+        // Derive a stable transportId from the WS URL hostname (same URL for
+        // the lifetime of this connector, so hostname is an appropriate stable key).
+        const transportId = (() => { try {
+            return new URL(url).hostname;
+        }
+        catch {
+            return url;
+        } })();
+        const emitConnectionState = (state) => {
+            if (state === lastConnectionState)
+                return;
+            lastConnectionState = state;
+            options.onConnectionStateChange?.(state);
+            options.onTransportEvent?.({ type: 'TRANSPORT_CONNECTION_STATE', transportId, state });
+        };
         // Bounded outbound message queue — max entries and total bytes, drop-oldest policy.
         // Messages pushed while the socket is not yet open or is reconnecting are buffered here
         // and flushed on the next successful open event.
@@ -256,10 +362,27 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
                 // reconnects stay observable after the first.
                 if (overflowEventCount === 1 || overflowEventCount % 10 === 0) {
                     queueOverflowNotified = true;
-                    options.onError?.(new WebSocketTransportError(`WebSocket outbound message too large (${sizeBytes} bytes, limit ${MAX_OUTBOUND_MESSAGE_BYTES}). Dropping the message while the socket reconnects.`, {
+                    const bpError = new WebSocketTransportError(`WebSocket outbound message too large (${sizeBytes} bytes, limit ${MAX_OUTBOUND_MESSAGE_BYTES}). Dropping the message while the socket reconnects.`, {
                         code: 'WS_QUEUE_OVERFLOW',
                         hint: 'Split large runtime event frames before enqueueing them while the WebSocket is disconnected.',
-                    }));
+                    });
+                    options.onError?.(bpError);
+                    options.onBackpressure?.({
+                        droppedCount: droppedOutboundCount,
+                        queueLength: outboundQueue.length,
+                        queueBytes: outboundQueueBytes,
+                        reason: 'message_too_large',
+                    });
+                    // Dispatch typed event so UI event-bus subscribers receive the same
+                    // information as the onBackpressure callback.
+                    options.onTransportEvent?.({
+                        type: 'TRANSPORT_BACKPRESSURE',
+                        transportId,
+                        droppedCount: droppedOutboundCount,
+                        queueLength: outboundQueue.length,
+                        queueBytes: outboundQueueBytes,
+                        reason: 'message_too_large',
+                    });
                 }
                 return;
             }
@@ -274,10 +397,27 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
                 // fire on first overflow and every 10th thereafter.
                 if (overflowEventCount === 1 || overflowEventCount % 10 === 0) {
                     queueOverflowNotified = true;
-                    options.onError?.(new WebSocketTransportError(`WebSocket outbound queue full (limit ${MAX_OUTBOUND_QUEUE} messages / ${MAX_OUTBOUND_QUEUE_BYTES} bytes). Dropping oldest messages until the socket reconnects.`, {
+                    const bpError = new WebSocketTransportError(`WebSocket outbound queue full (limit ${MAX_OUTBOUND_QUEUE} messages / ${MAX_OUTBOUND_QUEUE_BYTES} bytes). Dropping oldest messages until the socket reconnects.`, {
                         code: 'WS_QUEUE_OVERFLOW',
                         hint: 'Wait for the runtime event WebSocket to reconnect before sending more local frames.',
-                    }));
+                    });
+                    options.onError?.(bpError);
+                    options.onBackpressure?.({
+                        droppedCount: droppedOutboundCount,
+                        queueLength: outboundQueue.length,
+                        queueBytes: outboundQueueBytes,
+                        reason: 'queue_full',
+                    });
+                    // Dispatch typed event so UI event-bus subscribers receive the same
+                    // information as the onBackpressure callback.
+                    options.onTransportEvent?.({
+                        type: 'TRANSPORT_BACKPRESSURE',
+                        transportId,
+                        droppedCount: droppedOutboundCount,
+                        queueLength: outboundQueue.length,
+                        queueBytes: outboundQueueBytes,
+                        reason: 'queue_full',
+                    });
                 }
             }
             outboundQueue.push({ data, sizeBytes });
@@ -301,16 +441,36 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
             socket.close();
             socket = null;
         };
-        const scheduleReconnect = () => {
+        const scheduleReconnect = (reason = 'connection closed') => {
             if (!enabled || stopped)
                 return;
             const nextAttempt = reconnectAttempt + 1;
-            if (nextAttempt > reconnectPolicy.maxAttempts)
+            if (nextAttempt > reconnectPolicy.maxAttempts) {
+                emitConnectionState('failed');
                 return;
+            }
             reconnectAttempt = nextAttempt;
             // Use shared backoff helper so WS and SSE are on identical schedule.
             const delayMs = getStreamReconnectDelay(nextAttempt, reconnectPolicy);
+            // Fire legacy callback for backward compatibility AND new structured callback.
             options.onReconnect?.(nextAttempt, delayMs);
+            options.onReconnectAttempt?.({
+                attempt: nextAttempt,
+                maxAttempts: reconnectPolicy.maxAttempts,
+                delayMs,
+                reason,
+            });
+            // Dispatch typed event so UI event-bus subscribers receive the same
+            // metadata as the onReconnectAttempt callback.
+            options.onTransportEvent?.({
+                type: 'TRANSPORT_RECONNECT_ATTEMPT',
+                transportId,
+                attempt: nextAttempt,
+                maxAttempts: reconnectPolicy.maxAttempts,
+                delayMs,
+                reason,
+            });
+            emitConnectionState('reconnecting');
             reconnectTimer = setTimeout(() => {
                 reconnectTimer = null;
                 void connect().catch((error) => {
@@ -343,6 +503,10 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
             overflowEventCount = 0;
         };
         const onOpen = async (event) => {
+            // NOTE: do NOT call emitConnectionState('connecting') here — connect()
+            // already emits it before creating the socket. Calling it here would
+            // be a dedup-suppressed no-op (lastConnectionState is already 'connecting')
+            // and is semantically wrong since the socket is now open, not connecting.
             const candidateSocket = event.currentTarget;
             const openedSocket = candidateSocket && typeof candidateSocket.send === 'function'
                 ? candidateSocket
@@ -374,6 +538,7 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
                     ...(wsTraceHeaders['tracestate'] ? { tracestate: wsTraceHeaders['tracestate'] } : {}),
                 }));
                 flushOutboundQueue(openedSocket);
+                emitConnectionState('connected');
                 options.onOpen?.();
             }
             catch (error) {
@@ -436,13 +601,43 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
         };
         const onClose = (event) => {
             hasReceivedMessage = false;
-            if (!stopped && event.code !== 1000 && event.code !== 1005) {
+            // RFC 6455 §7.4.1: code 1005 (No Status Received) is synthesized by runtimes
+            // when a socket closes WITHOUT a close frame — including abnormal drops (process
+            // death, proxy teardown, RST) where wasClean === false. Only a genuine clean
+            // shutdown has wasClean === true AND code === 1000. Everything else must reconnect.
+            //
+            // Compatibility note: the `wasClean` field is present on the browser CloseEvent
+            // and on the 'ws' package's CloseEvent (used by Node.js and Bun). If a runtime
+            // somehow does not expose wasClean, `event.wasClean` is undefined (falsy), so
+            // the expression `event.wasClean === true` correctly falls back to reconnecting
+            // for any ambiguous close — never suppresses reconnect incorrectly.
+            const isCleanClose = event.wasClean === true && event.code === 1000;
+            if (!stopped && !isCleanClose) {
+                // Abnormal close — surface error and schedule reconnect.
+                // The raw close reason is forwarded so TRANSPORT_RECONNECT_ATTEMPT
+                // metadata is meaningful to diagnostic UIs.
                 const closeError = webSocketCloseError(event);
                 invokeTransportObserver(() => observer?.onError?.(closeError), observer?.onObserverError);
                 options.onError?.(closeError);
+                closeSocket();
+                // Pass the close reason so reconnect metadata is meaningful.
+                const rawReason = typeof event.reason === 'string' && event.reason.trim()
+                    ? event.reason.trim()
+                    : `code=${event.code}`;
+                scheduleReconnect(rawReason);
+            }
+            else {
+                // Clean close (wasClean === true && code === 1000) — deliberate server-side
+                // disconnect. We do NOT schedule a reconnect: the server explicitly terminated
+                // the session and the client should stay disconnected.
+                //
+                // **Contract:** `scheduleReconnect` is only called for non-clean closes.
+                // UIs observing `TRANSPORT_CONNECTION_STATE` will see the state transition
+                // to 'disconnected' emitted directly here in onClose, and will NOT see
+                // 'reconnecting' following a clean close.
+                closeSocket();
+                emitConnectionState('disconnected');
             }
-            closeSocket();
-            scheduleReconnect();
         };
         const onError = (event) => {
             const streamError = webSocketEventError(event, socket, url);
@@ -453,6 +648,7 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
             if (stopped)
                 return;
             closeSocket();
+            emitConnectionState('connecting');
             const nextSocket = new WebSocketImpl(url);
             socket = nextSocket;
             nextSocket.addEventListener('open', onOpen);
@@ -470,6 +666,7 @@ export function createWebSocketConnector(baseUrl, token, WebSocketImpl, options
                 clearTimeout(reconnectTimer);
             }
             closeSocket();
+            emitConnectionState('disconnected');
             // reset the outbound buffer on disposal so a future reconnect
             // (or re-use of the returned cleanup path in tests) does not accumulate
             // stale byte totals. Both must be reset together to prevent accounting drift.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-transport-realtime",
-  "version": "0.33.36",
+  "version": "0.33.38",
   "engines": {
     "bun": "1.3.10",
     "node": ">=22.0.0"
@@ -45,10 +45,10 @@
     "events"
   ],
   "dependencies": {
-    "@pellux/goodvibes-contracts": "0.33.36",
-    "@pellux/goodvibes-errors": "0.33.36",
-    "@pellux/goodvibes-transport-core": "0.33.36",
-    "@pellux/goodvibes-transport-http": "0.33.36"
+    "@pellux/goodvibes-contracts": "0.33.38",
+    "@pellux/goodvibes-errors": "0.33.38",
+    "@pellux/goodvibes-transport-core": "0.33.38",
+    "@pellux/goodvibes-transport-http": "0.33.38"
   },
   "publishConfig": {
     "access": "public"