@lspeasy/client 3.0.1 → 3.0.3

package/dist/connection/health.d.ts

@@ -7,15 +7,47 @@ type HealthEventMap = {
 };
 /**
  * Tracks connection state transitions and message activity timestamps.
+ *
+ * @remarks
+ * `ConnectionHealthTracker` is created internally by `LSPClient` and exposed
+ * via `client.connectionHealth`. Subscribe to `stateChanged` and
+ * `healthChanged` events to react to disconnections or transport failures.
+ *
+ * @useWhen
+ * You need to monitor connection liveness — for example, to show a status
+ * indicator, trigger reconnection logic, or surface transport errors to users.
+ *
+ * @see {@link HeartbeatMonitor} for detecting silent transport failures with
+ * periodic ping/pong checks.
+ *
+ * @never
+ * NEVER mutate the object returned by `getHealth()` — it is a defensive copy
+ * but consumers that store a reference and then modify it will see stale state.
+ *
+ * NEVER call `setState` from outside `LSPClient` internals. External callers
+ * have no knowledge of the full state-transition graph; setting state directly
+ * can desync the client's internal bookkeeping from the tracker's reported state.
+ *
+ * @category Client
  */
 export declare class ConnectionHealthTracker extends DisposableEventEmitter<HealthEventMap> {
     private health;
     /**
      * Returns a defensive copy of the current health snapshot.
+     *
+     * @returns A shallow copy of the current {@link ConnectionHealth} object,
+     *   including a nested copy of `heartbeat` when present.
      */
     getHealth(): ConnectionHealth;
     /**
      * Updates connection state and emits state/health change events.
+     *
+     * @param next - The new {@link ConnectionState} to transition to.
+     * @param reason - Optional human-readable reason for the state transition
+     *   (e.g. `'Transport error'`). Included in the emitted `StateChangeEvent`.
+     *
+     * @see {@link ConnectionState} for valid state values.
+     * @see {@link ConnectionHealthTracker} for the full class contract.
      */
     setState(next: ConnectionState, reason?: string): void;
     /**
@@ -32,10 +64,18 @@ export declare class ConnectionHealthTracker extends DisposableEventEmitter<Heal
     setHeartbeat(status: HeartbeatStatus): void;
     /**
      * Subscribes to connection state transitions.
+     *
+     * @param handler - Callback invoked with a {@link StateChangeEvent} each time
+     *   the connection state changes.
+     * @returns An unsubscribe function — call it to remove the listener.
      */
     onStateChange(handler: (event: StateChangeEvent) => void): () => void;
     /**
      * Subscribes to health snapshot updates.
+     *
+     * @param handler - Callback invoked with the latest {@link ConnectionHealth}
+     *   snapshot after any state or activity change.
+     * @returns An unsubscribe function — call it to remove the listener.
      */
     onHealthChange(handler: (health: ConnectionHealth) => void): () => void;
 }

package/dist/connection/health.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/connection/health.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,KAAK,cAAc,GAAG;IACpB,YAAY,EAAE,CAAC,gBAAgB,CAAC,CAAC;IACjC,aAAa,EAAE,CAAC,gBAAgB,CAAC,CAAC;CACnC,CAAC;AAEF;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,sBAAsB,CAAC,cAAc,CAAC;IACjF,OAAO,CAAC,MAAM,CAIZ;IAEF;;OAEG;IACH,SAAS,IAAI,gBAAgB,CAa5B;IAED;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAkBrD;IAED;;OAEG;IACH,eAAe,IAAI,IAAI,CAMtB;IAED;;OAEG;IACH,mBAAmB,IAAI,IAAI,CAkB1B;IAED;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAM1C;IAED;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI,CAGpE;IAED;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI,CAGtE;CACF"}
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/connection/health.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,KAAK,cAAc,GAAG;IACpB,YAAY,EAAE,CAAC,gBAAgB,CAAC,CAAC;IACjC,aAAa,EAAE,CAAC,gBAAgB,CAAC,CAAC;CACnC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,uBAAwB,SAAQ,sBAAsB,CAAC,cAAc,CAAC;IACjF,OAAO,CAAC,MAAM,CAIZ;IAEF;;;;;OAKG;IACH,SAAS,IAAI,gBAAgB,CAa5B;IAED;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAkBrD;IAED;;OAEG;IACH,eAAe,IAAI,IAAI,CAMtB;IAED;;OAEG;IACH,mBAAmB,IAAI,IAAI,CAkB1B;IAED;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAM1C;IAED;;;;;;OAMG;IACH,aAAa,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI,CAGpE;IAED;;;;;;OAMG;IACH,cAAc,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI,CAGtE;CACF"}

package/dist/connection/health.js

@@ -2,6 +2,28 @@ import { DisposableEventEmitter } from '@lspeasy/core';
 import { ConnectionState } from './types.js';
 /**
  * Tracks connection state transitions and message activity timestamps.
+ *
+ * @remarks
+ * `ConnectionHealthTracker` is created internally by `LSPClient` and exposed
+ * via `client.connectionHealth`. Subscribe to `stateChanged` and
+ * `healthChanged` events to react to disconnections or transport failures.
+ *
+ * @useWhen
+ * You need to monitor connection liveness — for example, to show a status
+ * indicator, trigger reconnection logic, or surface transport errors to users.
+ *
+ * @see {@link HeartbeatMonitor} for detecting silent transport failures with
+ * periodic ping/pong checks.
+ *
+ * @never
+ * NEVER mutate the object returned by `getHealth()` — it is a defensive copy
+ * but consumers that store a reference and then modify it will see stale state.
+ *
+ * NEVER call `setState` from outside `LSPClient` internals. External callers
+ * have no knowledge of the full state-transition graph; setting state directly
+ * can desync the client's internal bookkeeping from the tracker's reported state.
+ *
+ * @category Client
  */
 export class ConnectionHealthTracker extends DisposableEventEmitter {
     health = {
@@ -11,6 +33,9 @@ export class ConnectionHealthTracker extends DisposableEventEmitter {
     };
     /**
      * Returns a defensive copy of the current health snapshot.
+     *
+     * @returns A shallow copy of the current {@link ConnectionHealth} object,
+     *   including a nested copy of `heartbeat` when present.
      */
     getHealth() {
         const baseHealth = {
@@ -26,6 +51,13 @@ export class ConnectionHealthTracker extends DisposableEventEmitter {
     }
     /**
      * Updates connection state and emits state/health change events.
+     *
+     * @param next - The new {@link ConnectionState} to transition to.
+     * @param reason - Optional human-readable reason for the state transition
+     *   (e.g. `'Transport error'`). Included in the emitted `StateChangeEvent`.
+     *
+     * @see {@link ConnectionState} for valid state values.
+     * @see {@link ConnectionHealthTracker} for the full class contract.
      */
     setState(next, reason) {
         if (this.health.state === next) {
@@ -84,6 +116,10 @@ export class ConnectionHealthTracker extends DisposableEventEmitter {
     }
     /**
      * Subscribes to connection state transitions.
+     *
+     * @param handler - Callback invoked with a {@link StateChangeEvent} each time
+     *   the connection state changes.
+     * @returns An unsubscribe function — call it to remove the listener.
      */
     onStateChange(handler) {
         const disposable = this.on('stateChanged', handler);
@@ -91,6 +127,10 @@ export class ConnectionHealthTracker extends DisposableEventEmitter {
     }
     /**
      * Subscribes to health snapshot updates.
+     *
+     * @param handler - Callback invoked with the latest {@link ConnectionHealth}
+     *   snapshot after any state or activity change.
+     * @returns An unsubscribe function — call it to remove the listener.
      */
     onHealthChange(handler) {
         const disposable = this.on('healthChanged', handler);

package/dist/connection/health.js.map

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

package/dist/connection/heartbeat.d.ts

@@ -10,6 +10,32 @@ export interface HeartbeatMonitorOptions {
 }
 /**
  * Runs interval-based heartbeat checks for active transports.
+ *
+ * @remarks
+ * Created internally by `LSPClient` when `ClientOptions.heartbeat` is
+ * configured. The monitor periodically sends a ping (via `onPing`) and checks
+ * whether a pong was received within `timeout` ms. If not, `onUnresponsive`
+ * is called so the client can close and attempt to reconnect.
+ *
+ * @useWhen
+ * You need to detect silent transport failures — for example, when the server
+ * process dies without closing the socket, leaving the client hanging
+ * indefinitely on pending requests.
+ *
+ * @avoidWhen
+ * The transport already provides its own keep-alive mechanism (e.g. WebSocket
+ * ping frames) — adding a heartbeat on top creates redundant round-trips and
+ * may interfere with the transport's own timeout logic.
+ *
+ * @never
+ * NEVER set `interval` shorter than the typical round-trip latency for your
+ * transport — doing so causes constant `onUnresponsive` callbacks on any
+ * non-local transport, triggering spurious reconnects.
+ *
+ * NEVER rely on heartbeat for authentication or access control. The heartbeat
+ * only confirms the transport is alive; it carries no identity information.
+ *
+ * @category Client
  */
 export declare class HeartbeatMonitor {
     private readonly options;
@@ -30,6 +56,9 @@ export declare class HeartbeatMonitor {
     markPong(): void;
     /**
      * Returns the latest heartbeat status snapshot.
+     *
+     * @returns A shallow copy of the current {@link HeartbeatStatus}, including
+     *   timing and responsiveness information.
      */
     getStatus(): HeartbeatStatus;
 }

package/dist/connection/heartbeat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../../src/connection/heartbeat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAIf,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,MAAM,CAAkB;IAEhC,YAA6B,OAAO,EAAE,uBAAuB,EAS5D;IAED;;OAEG;IACH,KAAK,IAAI,IAAI,CAuBZ;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,CAKX;IAED;;OAEG;IACH,QAAQ,IAAI,IAAI,CAWf;IAED;;OAEG;IACH,SAAS,IAAI,eAAe,CAE3B;CACF"}
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../../src/connection/heartbeat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,gBAAgB;IAIf,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,MAAM,CAAkB;IAEhC,YAA6B,OAAO,EAAE,uBAAuB,EAS5D;IAED;;OAEG;IACH,KAAK,IAAI,IAAI,CAuBZ;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,CAKX;IAED;;OAEG;IACH,QAAQ,IAAI,IAAI,CAWf;IAED;;;;;OAKG;IACH,SAAS,IAAI,eAAe,CAE3B;CACF"}

package/dist/connection/heartbeat.js

@@ -1,5 +1,31 @@
 /**
  * Runs interval-based heartbeat checks for active transports.
+ *
+ * @remarks
+ * Created internally by `LSPClient` when `ClientOptions.heartbeat` is
+ * configured. The monitor periodically sends a ping (via `onPing`) and checks
+ * whether a pong was received within `timeout` ms. If not, `onUnresponsive`
+ * is called so the client can close and attempt to reconnect.
+ *
+ * @useWhen
+ * You need to detect silent transport failures — for example, when the server
+ * process dies without closing the socket, leaving the client hanging
+ * indefinitely on pending requests.
+ *
+ * @avoidWhen
+ * The transport already provides its own keep-alive mechanism (e.g. WebSocket
+ * ping frames) — adding a heartbeat on top creates redundant round-trips and
+ * may interfere with the transport's own timeout logic.
+ *
+ * @never
+ * NEVER set `interval` shorter than the typical round-trip latency for your
+ * transport — doing so causes constant `onUnresponsive` callbacks on any
+ * non-local transport, triggering spurious reconnects.
+ *
+ * NEVER rely on heartbeat for authentication or access control. The heartbeat
+ * only confirms the transport is alive; it carries no identity information.
+ *
+ * @category Client
  */
 export class HeartbeatMonitor {
     options;
@@ -64,6 +90,9 @@ export class HeartbeatMonitor {
     }
     /**
      * Returns the latest heartbeat status snapshot.
+     *
+     * @returns A shallow copy of the current {@link HeartbeatStatus}, including
+     *   timing and responsiveness information.
      */
     getStatus() {
         return { ...this.status };

package/dist/connection/heartbeat.js.map

@@ -1 +1 @@
-{"version":3,"file":"heartbeat.js","sourceRoot":"","sources":["../../src/connection/heartbeat.ts"],"names":[],"mappings":"AAYA;;GAEG;AACH,MAAM,OAAO,gBAAgB;IAIE,OAAO;IAH5B,KAAK,CAA6B;IAClC,MAAM,CAAkB;IAEhC,YAA6B,OAAgC,EAAE;uBAAlC,OAAO;QAClC,IAAI,CAAC,MAAM,GAAG;YACZ,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,IAAI,KAAK;YACxC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ;YACjC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO;YAC/B,QAAQ,EAAE,IAAI;YACd,QAAQ,EAAE,IAAI;YACd,YAAY,EAAE,IAAI;SACnB,CAAC;IAAA,CACH;IAED;;OAEG;IACH,KAAK,GAAS;QACZ,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACvC,OAAO;QACT,CAAC;QAED,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;YAC7B,IAAI,CAAC,MAAM,GAAG;gBACZ,GAAG,IAAI,CAAC,MAAM;gBACd,QAAQ,EAAE,IAAI,IAAI,EAAE;aACrB,CAAC;YAEF,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YAEtB,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;YAE3C,IAAI,QAAQ,IAAI,QAAQ,IAAI,QAAQ,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAC1F,IAAI,CAAC,MAAM,GAAG;oBACZ,GAAG,IAAI,CAAC,MAAM;oBACd,YAAY,EAAE,KAAK;iBACpB,CAAC;gBACF,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;YAChC,CAAC;QAAA,CACF,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAAA,CAC1B;IAED;;OAEG;IACH,IAAI,GAAS;QACX,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;QACzB,CAAC;IAAA,CACF;IAED;;OAEG;IACH,QAAQ,GAAS;QACf,MAAM,eAAe,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC;QAClD,IAAI,CAAC,MAAM,GAAG;YACZ,GAAG,IAAI,CAAC,MAAM;YACd,QAAQ,EAAE,IAAI,IAAI,EAAE;YACpB,YAAY,EAAE,IAAI;SACnB,CAAC;QAEF,IAAI,eAAe,EAAE,CAAC;YACpB,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC;QAChC,CAAC;IAAA,CACF;IAED;;OAEG;IACH,SAAS,GAAoB;QAC3B,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAAA,CAC3B;CACF"}
+{"version":3,"file":"heartbeat.js","sourceRoot":"","sources":["../../src/connection/heartbeat.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,OAAO,gBAAgB;IAIE,OAAO;IAH5B,KAAK,CAA6B;IAClC,MAAM,CAAkB;IAEhC,YAA6B,OAAgC;uBAAhC,OAAO;QAClC,IAAI,CAAC,MAAM,GAAG;YACZ,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,IAAI,KAAK;YACxC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ;YACjC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO;YAC/B,QAAQ,EAAE,IAAI;YACd,QAAQ,EAAE,IAAI;YACd,YAAY,EAAE,IAAI;SACnB,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACvC,OAAO;QACT,CAAC;QAED,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;YAC5B,IAAI,CAAC,MAAM,GAAG;gBACZ,GAAG,IAAI,CAAC,MAAM;gBACd,QAAQ,EAAE,IAAI,IAAI,EAAE;aACrB,CAAC;YAEF,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YAEtB,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;YAE3C,IAAI,QAAQ,IAAI,QAAQ,IAAI,QAAQ,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAC1F,IAAI,CAAC,MAAM,GAAG;oBACZ,GAAG,IAAI,CAAC,MAAM;oBACd,YAAY,EAAE,KAAK;iBACpB,CAAC;gBACF,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;YAChC,CAAC;QACH,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,IAAI;QACF,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;QACzB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,MAAM,eAAe,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC;QAClD,IAAI,CAAC,MAAM,GAAG;YACZ,GAAG,IAAI,CAAC,MAAM;YACd,QAAQ,EAAE,IAAI,IAAI,EAAE;YACpB,YAAY,EAAE,IAAI;SACnB,CAAC;QAEF,IAAI,eAAe,EAAE,CAAC;YACpB,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC;QAChC,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,SAAS;QACP,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5B,CAAC;CACF"}

package/dist/connection/partial-result-collector.js.map

@@ -1 +1 @@
-{"version":3,"file":"partial-result-collector.js","sourceRoot":"","sources":["../../src/connection/partial-result-collector.ts"],"names":[],"mappings":"AAOA,yFAAyF;AACzF,MAAM,OAAO,sBAAsB;IAChB,UAAU,GAAG,IAAI,GAAG,EAAqC,CAAC;IAE3E,KAAK,CAAW,KAAoB,EAAE,SAAoC,EAAQ;QAChF,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE;YACzB,QAAQ,EAAE,EAAE;YACZ,SAAS,EAAE,SAAqC;SACjD,CAAC,CAAC;IAAA,CACJ;IAED,IAAI,CAAC,KAAoB,EAAE,KAAc,EAAW;QAClD,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC7C,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO,KAAK,CAAC;QACf,CAAC;QAED,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC/B,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC3B,OAAO,IAAI,CAAC;IAAA,CACb;IAED,MAAM,CAAW,KAAoB,EAAc;QACjD,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC7C,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC9B,OAAO,SAAS,CAAC,QAAsB,CAAC;IAAA,CACzC;IAED,KAAK,CAAC,KAAoB,EAAQ;QAChC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAAA,CAC/B;IAED,KAAK,GAAS;QACZ,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IAAA,CACzB;CACF"}
+{"version":3,"file":"partial-result-collector.js","sourceRoot":"","sources":["../../src/connection/partial-result-collector.ts"],"names":[],"mappings":"AAOA,yFAAyF;AACzF,MAAM,OAAO,sBAAsB;IAChB,UAAU,GAAG,IAAI,GAAG,EAAqC,CAAC;IAE3E,KAAK,CAAW,KAAoB,EAAE,SAAoC;QACxE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE;YACzB,QAAQ,EAAE,EAAE;YACZ,SAAS,EAAE,SAAqC;SACjD,CAAC,CAAC;IACL,CAAC;IAED,IAAI,CAAC,KAAoB,EAAE,KAAc;QACvC,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC7C,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO,KAAK,CAAC;QACf,CAAC;QAED,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC/B,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,CAAW,KAAoB;QACnC,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC7C,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC9B,OAAO,SAAS,CAAC,QAAsB,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,KAAoB;QACxB,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;CACF"}

package/dist/connection/registration-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"registration-store.js","sourceRoot":"","sources":["../../src/connection/registration-store.ts"],"names":[],"mappings":"AAEA,+FAA+F;AAC/F,MAAM,OAAO,iBAAiB;IACX,iBAAiB,GAAG,IAAI,GAAG,EAA+B,CAAC;IAE5E,MAAM,CAAC,YAAiC,EAAQ;QAC9C,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC;IAAA,CAC3D;IAED,MAAM,CAAC,EAAU,EAAmC;QAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChD,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAClC,OAAO,QAAQ,CAAC;IAAA,CACjB;IAED,MAAM,GAA0B;QAC9B,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC;IAAA,CACpD;IAED,GAAG,CAAC,EAAU,EAAW;QACvB,OAAO,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAAA,CACvC;IAED,KAAK,GAAS;QACZ,IAAI,CAAC,iBAAiB,CAAC,KAAK,EAAE,CAAC;IAAA,CAChC;CACF"}
+{"version":3,"file":"registration-store.js","sourceRoot":"","sources":["../../src/connection/registration-store.ts"],"names":[],"mappings":"AAEA,+FAA+F;AAC/F,MAAM,OAAO,iBAAiB;IACX,iBAAiB,GAAG,IAAI,GAAG,EAA+B,CAAC;IAE5E,MAAM,CAAC,YAAiC;QACtC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC;IAC5D,CAAC;IAED,MAAM,CAAC,EAAU;QACf,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChD,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAClC,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM;QACJ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC;IACrD,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACxC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,iBAAiB,CAAC,KAAK,EAAE,CAAC;IACjC,CAAC;CACF"}

package/dist/connection/types.d.ts

@@ -1,5 +1,14 @@
 /**
- * Lifecycle state for the client connection.
+ * Lifecycle state of an `LSPClient` connection.
+ *
+ * @remarks
+ * Transitions: `Disconnected` → `Connecting` (on `connect()`) → `Connected`
+ * (after `initialized`) → `Disconnecting` (on `disconnect()`) →
+ * `Disconnected`.
+ *
+ * Listen for state changes via `LSPClient.onConnectionStateChange`.
+ *
+ * @category Client
  */
 export declare enum ConnectionState {
     Connecting = "connecting",
@@ -9,39 +18,72 @@ export declare enum ConnectionState {
 }
 /**
  * Configuration for optional heartbeat monitoring.
+ *
+ * @remarks
+ * When `enabled` is `true`, the client sends a `$/ping` request at each
+ * `interval` milliseconds. If no response arrives within `timeout`
+ * milliseconds, the connection is marked unresponsive.
+ *
+ * @config
+ * @category Client
  */
 export interface HeartbeatConfig {
+    /** Whether heartbeat monitoring is active. */
     enabled?: boolean;
+    /** Interval between pings in milliseconds. */
     interval: number;
+    /** Time to wait for a pong response in milliseconds. */
     timeout: number;
 }
 /**
- * Runtime heartbeat status snapshot.
+ * Snapshot of the current heartbeat monitoring status.
+ *
+ * @category Client
  */
 export interface HeartbeatStatus {
+    /** Whether heartbeat monitoring is active. */
     enabled: boolean;
+    /** Interval between pings in milliseconds. */
     interval: number;
+    /** Timeout in milliseconds before a ping is considered unanswered. */
     timeout: number;
+    /** Timestamp of the last outgoing ping, or `null` if no ping has been sent. */
     lastPing: Date | null;
+    /** Timestamp of the last received pong, or `null` if no pong has been received. */
     lastPong: Date | null;
+    /** Whether the server responded to the most recent ping within the timeout window. */
     isResponsive: boolean;
 }
 /**
- * Aggregated connection health details.
+ * Aggregated connection health snapshot returned by
+ * `LSPClient.getConnectionHealth()`.
+ *
+ * @category Client
  */
 export interface ConnectionHealth {
+    /** Current lifecycle state of the connection. */
     state: ConnectionState;
+    /** Timestamp of the last outgoing message, or `null` if none has been sent. */
     lastMessageSent: Date | null;
+    /** Timestamp of the last incoming message, or `null` if none has been received. */
     lastMessageReceived: Date | null;
+    /** Heartbeat monitoring snapshot, present only when heartbeat is configured. */
     heartbeat?: HeartbeatStatus;
 }
 /**
- * Event payload emitted when connection state changes.
+ * Payload emitted when the connection state changes.
+ * Subscribe via `LSPClient.onConnectionStateChange()`.
+ *
+ * @category Client
  */
 export interface StateChangeEvent {
+    /** The state the connection was in before this transition. */
     previous: ConnectionState;
+    /** The state the connection has transitioned into. */
     current: ConnectionState;
+    /** Wall-clock time at which the state transition occurred. */
     timestamp: Date;
+    /** Optional human-readable description of why the state changed. */
     reason?: string;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/connection/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/connection/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,eAAe;IACzB,UAAU,eAAe;IACzB,SAAS,cAAc;IACvB,aAAa,kBAAkB;IAC/B,YAAY,iBAAiB;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,eAAe,CAAC;IACvB,eAAe,EAAE,IAAI,GAAG,IAAI,CAAC;IAC7B,mBAAmB,EAAE,IAAI,GAAG,IAAI,CAAC;IACjC,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,eAAe,CAAC;IAC1B,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,IAAI,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/connection/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,oBAAY,eAAe;IACzB,UAAU,eAAe;IACzB,SAAS,cAAc;IACvB,aAAa,kBAAkB;IAC/B,YAAY,iBAAiB;CAC9B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,mFAAmF;IACnF,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,sFAAsF;IACtF,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,KAAK,EAAE,eAAe,CAAC;IACvB,+EAA+E;IAC/E,eAAe,EAAE,IAAI,GAAG,IAAI,CAAC;IAC7B,mFAAmF;IACnF,mBAAmB,EAAE,IAAI,GAAG,IAAI,CAAC;IACjC,gFAAgF;IAChF,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,QAAQ,EAAE,eAAe,CAAC;IAC1B,sDAAsD;IACtD,OAAO,EAAE,eAAe,CAAC;IACzB,8DAA8D;IAC9D,SAAS,EAAE,IAAI,CAAC;IAChB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/connection/types.js

@@ -1,8 +1,16 @@
-export { ConnectionState };
 /**
- * Lifecycle state for the client connection.
+ * Lifecycle state of an `LSPClient` connection.
+ *
+ * @remarks
+ * Transitions: `Disconnected` → `Connecting` (on `connect()`) → `Connected`
+ * (after `initialized`) → `Disconnecting` (on `disconnect()`) →
+ * `Disconnected`.
+ *
+ * Listen for state changes via `LSPClient.onConnectionStateChange`.
+ *
+ * @category Client
  */
-var ConnectionState;
+export var ConnectionState;
 (function (ConnectionState) {
     ConnectionState["Connecting"] = "connecting";
     ConnectionState["Connected"] = "connected";

package/dist/connection/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/connection/types.ts"],"names":[],"mappings":"SAGY,eAAe;AAH3B;;GAEG;AACH,IAAY,eAKX;AALD,WAAY,eAAe;IACzB,4CAAyB,CAAA;IACzB,0CAAuB,CAAA;IACvB,kDAA+B,CAAA;IAC/B,gDAA6B,CAAA;AAAA,CAC/B,EALY,eAAe,KAAf,eAAe,QAK1B"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/connection/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,CAAN,IAAY,eAKX;AALD,WAAY,eAAe;IACzB,4CAAyB,CAAA;IACzB,0CAAuB,CAAA;IACvB,kDAA+B,CAAA;IAC/B,gDAA6B,CAAA;AAC/B,CAAC,EALW,eAAe,KAAf,eAAe,QAK1B"}

package/dist/index.d.ts

@@ -1,5 +1,52 @@
 /**
- * @lspeasy/client - LSP Client for connecting to language servers
+ * LSP client package for connecting to language servers.
+ *
+ * @remarks
+ * Use `@lspeasy/client` when you need to build the **consumer** side of the
+ * Language Server Protocol — an editor extension, a CLI analysis tool, a test
+ * harness, or any process that speaks to a language server process.
+ *
+ * The primary entry point is {@link LSPClient}. Construct it with
+ * {@link ClientOptions}, call `connect(transport)` to complete the LSP
+ * handshake, then use `expect<ServerCaps>()` to get typed access to
+ * capability-aware namespaces (e.g. `client.textDocument.hover(params)`).
+ *
+ * ### Transport Decision Tree
+ *
+ * **Stdio** (`StdioTransport` from `@lspeasy/core/node`)
+ * — Use when: spawning the language server as a child process (the canonical
+ *   editor extension pattern). Zero network overhead; server and client share
+ *   a lifespan. Failure mode: server process dies silently → stdout EOF fires
+ *   `onClose`; pair with `HeartbeatMonitor` on long-lived processes.
+ *
+ * **WebSocket** (`WebSocketTransport` from `@lspeasy/core`)
+ * — Use when: the language server runs remotely (CI, container, cloud dev env)
+ *   or must be browser-accessible. Supports reconnect with exponential back-off.
+ *   Failure mode: network partition → `onError` fires without `onClose`;
+ *   enable `enableReconnect` and subscribe to `ConnectionHealthTracker` events.
+ *
+ * **TCP** (`TcpTransport` from `@lspeasy/core/node`)
+ * — Use when: you need a persistent local socket and control both ends
+ *   (e.g. a test harness or a daemon that outlives the client process).
+ *   Failure mode: port conflict at startup; use `mode: 'client'` only after
+ *   confirming the server is listening, or wrap in a retry loop.
+ *
+ * **DedicatedWorkerTransport** (`DedicatedWorkerTransport` from `@lspeasy/core`)
+ * — Use when: running the language server in a Web Worker for browser isolation.
+ *   Zero latency (shared memory), no WebSocket overhead. Failure mode: worker
+ *   uncaught exception terminates silently; subscribe to `worker.onerror`.
+ *
+ * ### Connection health
+ * Use {@link ConnectionHealthTracker} and {@link HeartbeatMonitor} to detect
+ * silent transport failures. Subscribe to state-change events via
+ * {@link ConnectionState}.
+ *
+ * ### Dynamic registration
+ * The client handles `client/registerCapability` and
+ * `client/unregisterCapability` requests from the server automatically,
+ * updating the typed namespaces at runtime.
+ *
+ * @packageDocumentation
  */
 export { LSPClient } from './client.js';
 export { CapabilityGuard, ClientCapabilityGuard } from './capability-guard.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,yBAAyB,EACzB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACnG,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,YAAY,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAGxE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,yBAAyB,EACzB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACnG,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,YAAY,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAGxE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -1,5 +1,52 @@
 /**
- * @lspeasy/client - LSP Client for connecting to language servers
+ * LSP client package for connecting to language servers.
+ *
+ * @remarks
+ * Use `@lspeasy/client` when you need to build the **consumer** side of the
+ * Language Server Protocol — an editor extension, a CLI analysis tool, a test
+ * harness, or any process that speaks to a language server process.
+ *
+ * The primary entry point is {@link LSPClient}. Construct it with
+ * {@link ClientOptions}, call `connect(transport)` to complete the LSP
+ * handshake, then use `expect<ServerCaps>()` to get typed access to
+ * capability-aware namespaces (e.g. `client.textDocument.hover(params)`).
+ *
+ * ### Transport Decision Tree
+ *
+ * **Stdio** (`StdioTransport` from `@lspeasy/core/node`)
+ * — Use when: spawning the language server as a child process (the canonical
+ *   editor extension pattern). Zero network overhead; server and client share
+ *   a lifespan. Failure mode: server process dies silently → stdout EOF fires
+ *   `onClose`; pair with `HeartbeatMonitor` on long-lived processes.
+ *
+ * **WebSocket** (`WebSocketTransport` from `@lspeasy/core`)
+ * — Use when: the language server runs remotely (CI, container, cloud dev env)
+ *   or must be browser-accessible. Supports reconnect with exponential back-off.
+ *   Failure mode: network partition → `onError` fires without `onClose`;
+ *   enable `enableReconnect` and subscribe to `ConnectionHealthTracker` events.
+ *
+ * **TCP** (`TcpTransport` from `@lspeasy/core/node`)
+ * — Use when: you need a persistent local socket and control both ends
+ *   (e.g. a test harness or a daemon that outlives the client process).
+ *   Failure mode: port conflict at startup; use `mode: 'client'` only after
+ *   confirming the server is listening, or wrap in a retry loop.
+ *
+ * **DedicatedWorkerTransport** (`DedicatedWorkerTransport` from `@lspeasy/core`)
+ * — Use when: running the language server in a Web Worker for browser isolation.
+ *   Zero latency (shared memory), no WebSocket overhead. Failure mode: worker
+ *   uncaught exception terminates silently; subscribe to `worker.onerror`.
+ *
+ * ### Connection health
+ * Use {@link ConnectionHealthTracker} and {@link HeartbeatMonitor} to detect
+ * silent transport failures. Subscribe to state-change events via
+ * {@link ConnectionState}.
+ *
+ * ### Dynamic registration
+ * The client handles `client/registerCapability` and
+ * `client/unregisterCapability` requests from the server automatically,
+ * updating the typed namespaces at runtime.
+ *
+ * @packageDocumentation
  */
 export { LSPClient } from './client.js';
 export { CapabilityGuard, ClientCapabilityGuard } from './capability-guard.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAS/E,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAOnG,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAS/E,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAOnG,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/notifications/wait.d.ts

@@ -1,12 +1,63 @@
 /**
- * Configuration for waiting on a specific notification.
+ * Options for `NotificationWaiter` and `LSPClient.waitForNotification`.
+ *
+ * @config
+ * @typeParam TParams - The notification params type for the awaited method.
+ * @category Client
  */
 export interface NotificationWaitOptions<TParams> {
+    /**
+     * Maximum time to wait in milliseconds before rejecting with a timeout error.
+     */
     timeout: number;
+    /**
+     * Optional predicate to skip notifications that don't match the expected
+     * content. The waiter continues listening until a matching notification
+     * arrives or the timeout expires.
+     */
     filter?: (params: TParams) => boolean;
 }
 /**
- * Tracks a single wait-for-notification operation and timeout lifecycle.
+ * Tracks a single wait-for-notification operation and its timeout lifecycle.
+ *
+ * @remarks
+ * Created internally by `LSPClient.waitForNotification`. Use
+ * `LSPClient.waitForNotification` rather than instantiating this class
+ * directly.
+ *
+ * @useWhen
+ * You need to await a specific server-to-client notification after triggering
+ * a server-side operation — for example, waiting for
+ * `textDocument/publishDiagnostics` after saving a document.
+ *
+ * @avoidWhen
+ * You need to listen for ongoing notifications (not a one-shot wait) — use
+ * `LSPClient.onNotification` for persistent subscriptions instead.
+ *
+ * @never
+ * NEVER create a `NotificationWaiter` without setting a timeout — an
+ * indefinite wait will leak the waiter permanently if the notification never
+ * arrives (e.g. the server suppresses it for certain file types).
+ *
+ * NEVER use `NotificationWaiter` to wait for notifications that arrive before
+ * the waiter is registered. The waiter only sees notifications emitted after
+ * `start()` is called; earlier notifications are silently missed.
+ *
+ * @example
+ * ```ts
+ * // Wait for diagnostics after saving
+ * const diags = await client.waitForNotification(
+ *   'textDocument/publishDiagnostics',
+ *   {
+ *     timeout: 5000,
+ *     filter: (params) => params.uri === 'file:///src/main.ts',
+ *   }
+ * );
+ * console.log(diags.diagnostics);
+ * ```
+ *
+ * @typeParam TParams - The notification params type.
+ * @category Client
  */
 export declare class NotificationWaiter<TParams> {
     private readonly method;
@@ -22,6 +73,10 @@ export declare class NotificationWaiter<TParams> {
     start(): void;
     /**
      * Returns whether an incoming notification satisfies this waiter.
+     *
+     * @param method - The notification method string of the incoming message.
+     * @param params - The notification params to test against the optional filter predicate.
+     * @returns `true` when the method matches and the filter (if any) passes.
      */
     matches(method: string, params: TParams): boolean;
     /**

package/dist/notifications/wait.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../src/notifications/wait.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,uBAAuB,CAAC,OAAO;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;CACvC;AAED;;GAEG;AACH,qBAAa,kBAAkB,CAAC,OAAO;IAMnC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAGxB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAT5B,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAElD,YACmB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,uBAAuB,CAAC,OAAO,CAAC,EAC1D,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,EAClC,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,EACb,SAAS,EAAE,MAAM,IAAI,EAIvC;IAED;;OAEG;IACH,KAAK,IAAI,IAAI,CASZ;IAED;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAUhD;IAED;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAG7B;IAED;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAGzB;IAED;;OAEG;IACH,OAAO,IAAI,IAAI,CAOd;CACF"}
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../src/notifications/wait.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB,CAAC,OAAO;IAC9C;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,qBAAa,kBAAkB,CAAC,OAAO;IAMnC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAGxB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAT5B,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAElD,YACmB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,uBAAuB,CAAC,OAAO,CAAC,EAC1D,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,EAClC,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,EACb,SAAS,EAAE,MAAM,IAAI,EAIvC;IAED;;OAEG;IACH,KAAK,IAAI,IAAI,CASZ;IAED;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAUhD;IAED;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAG7B;IAED;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAGzB;IAED;;OAEG;IACH,OAAO,IAAI,IAAI,CAOd;CACF"}