@myrialabs/ptykit 0.0.1

package/dist/client/pty-kit-client.js

@@ -0,0 +1,245 @@
+/**
+ * `PtyKitClient` — the browser client.
+ *
+ * One `WsCore` socket multiplexes every session in a namespace. Server output
+ * broadcasts to the room; this client filters by `sessionId` and dedups by
+ * `seq` (R5). Replayed frames (no `seq`) are passed through `stripReportRequests`
+ * so the terminal does not answer color/cursor queries into an idle prompt (R17).
+ *
+ * Reconnect is ON by default; on reconnect every known session is re-attached
+ * (idempotent `create-session`) so the room subscription and scrollback recover
+ * (R7/R14).
+ */
+import { stripReportRequests } from '../shared/index.js';
+import { WsCore, } from './ws-core.js';
+import { defaultPersistence } from './persistence.js';
+/** A handle to one PTY session over the shared socket. */
+export class ClientSession {
+    client;
+    sessionId;
+    namespace;
+    /** @internal — the request used to (re)attach on reconnect. */
+    createRequest;
+    lastSeq = 0;
+    /** Output that arrived before the first `onData` listener (e.g. reattach replay). */
+    pending = [];
+    pendingBytes = 0;
+    static PENDING_CAP = 1_000_000; // 1MB backlog ceiling
+    dataCbs = new Set();
+    exitCbs = new Set();
+    dirCbs = new Set();
+    errCbs = new Set();
+    constructor(client, request) {
+        this.client = client;
+        this.sessionId = request.sessionId;
+        this.namespace = request.namespace;
+        this.createRequest = request;
+    }
+    /** Subscribe to terminal output (deduped by seq; replay frames stripped). */
+    onData(cb) {
+        this.dataCbs.add(cb);
+        // Flush output that arrived before any listener (the reattach replay
+        // frame is unicast during `attach`, before the caller subscribes).
+        if (this.pending.length) {
+            const buffered = this.pending;
+            this.pending = [];
+            this.pendingBytes = 0;
+            for (const chunk of buffered)
+                cb(chunk);
+        }
+        return () => this.dataCbs.delete(cb);
+    }
+    onExit(cb) {
+        this.exitCbs.add(cb);
+        return () => this.exitCbs.delete(cb);
+    }
+    onDirectory(cb) {
+        this.dirCbs.add(cb);
+        return () => this.dirCbs.delete(cb);
+    }
+    onError(cb) {
+        this.errCbs.add(cb);
+        return () => this.errCbs.delete(cb);
+    }
+    /** @internal Route an output event for this session. */
+    _handleOutput(content, seq) {
+        let deliver;
+        if (seq === undefined) {
+            // Replay frame — strip report-requests so xterm doesn't answer into the
+            // idle prompt (R17). No seq tracking; replay is a full screen frame.
+            deliver = stripReportRequests(content);
+        }
+        else {
+            if (seq <= this.lastSeq)
+                return; // dedup live output (R5)
+            this.lastSeq = seq;
+            deliver = content;
+        }
+        if (this.dataCbs.size === 0) {
+            this.pending.push(deliver);
+            this.pendingBytes += deliver.length;
+            while (this.pendingBytes > ClientSession.PENDING_CAP && this.pending.length > 1) {
+                this.pendingBytes -= this.pending.shift().length;
+            }
+            return;
+        }
+        for (const cb of this.dataCbs)
+            cb(deliver);
+    }
+    /** @internal */
+    _handleExit(exitCode) {
+        for (const cb of this.exitCbs)
+            cb(exitCode);
+    }
+    /** @internal */
+    _handleDirectory(directory) {
+        for (const cb of this.dirCbs)
+            cb(directory);
+    }
+    /** @internal */
+    _handleError(error) {
+        for (const cb of this.errCbs)
+            cb(error);
+    }
+    /** Send raw keystrokes (fire-and-forget pass-through, R16). */
+    write(data) {
+        this.client._emitInput(this.sessionId, data);
+    }
+    resize(cols, rows) {
+        return this.client._resize(this.sessionId, cols, rows);
+    }
+    cancel() {
+        return this.client._cancel(this.sessionId);
+    }
+    clear() {
+        return this.client._clear(this.sessionId);
+    }
+    /** Kill the session on the server. */
+    kill() {
+        return this.client._kill(this.sessionId);
+    }
+    /** Stop receiving locally; does NOT kill the server-side session. */
+    detach() {
+        this.dataCbs.clear();
+        this.exitCbs.clear();
+        this.dirCbs.clear();
+        this.errCbs.clear();
+        this.client._forget(this.sessionId);
+    }
+}
+export class PtyKitClient {
+    core;
+    persistence;
+    defaultNamespace;
+    sessions = new Map();
+    status = 'reconnecting';
+    statusCbs = new Set();
+    constructor(options) {
+        this.persistence = options.persistence ?? defaultPersistence();
+        this.defaultNamespace = options.namespace;
+        this.core = new WsCore({
+            url: options.url,
+            reconnect: options.reconnect,
+            WebSocketImpl: options.WebSocketImpl,
+            requestTimeoutMs: options.requestTimeoutMs,
+            onStatus: (s) => {
+                this.status = s;
+                for (const cb of this.statusCbs)
+                    cb(s);
+            },
+            onReconnect: () => this.reattachAll(),
+        });
+        // Route broadcast events to the matching session.
+        this.core.on('output', (p) => this.sessions.get(p?.sessionId)?._handleOutput(p.content, p.seq));
+        this.core.on('exit', (p) => this.sessions.get(p?.sessionId)?._handleExit(p.exitCode));
+        this.core.on('directory', (p) => this.sessions.get(p?.sessionId)?._handleDirectory(p.newDirectory));
+        this.core.on('error', (p) => this.sessions.get(p?.sessionId)?._handleError(p.error));
+    }
+    /** Subscribe to connection status. Fires immediately with the current value. */
+    onStatus(cb) {
+        this.statusCbs.add(cb);
+        cb(this.status);
+        return () => this.statusCbs.delete(cb);
+    }
+    connected() {
+        return this.core.connected();
+    }
+    resolveNamespace(ns) {
+        const namespace = ns ?? this.defaultNamespace;
+        if (!namespace)
+            throw new Error('ptykit: a namespace is required (set it on the client or the call)');
+        return namespace;
+    }
+    generateId(namespace) {
+        return `${namespace}-terminal-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    }
+    /** Create a new session (or attach if the id already exists — server is idempotent). */
+    async create(options = {}) {
+        const namespace = this.resolveNamespace(options.namespace);
+        const sessionId = options.sessionId ?? this.generateId(namespace);
+        this.persistence.save(namespace, sessionId);
+        return this.open({ sessionId, namespace, cwd: options.cwd, cols: options.cols, rows: options.rows, shell: options.shell });
+    }
+    /** Attach to an existing session (replays serialized scrollback). */
+    async attach(sessionId, options = {}) {
+        const namespace = this.resolveNamespace(options.namespace);
+        const id = sessionId ?? this.persistence.load(namespace);
+        if (!id)
+            throw new Error('ptykit: no sessionId provided and none persisted for this namespace');
+        this.persistence.save(namespace, id);
+        return this.open({ sessionId: id, namespace, cwd: options.cwd, cols: options.cols, rows: options.rows, shell: options.shell });
+    }
+    async open(request) {
+        let session = this.sessions.get(request.sessionId);
+        if (!session) {
+            session = new ClientSession(this, request);
+            this.sessions.set(request.sessionId, session);
+        }
+        // Listener is registered (above) before the request is sent, so the replay
+        // frame the server unicasts is captured by this session.
+        await this.core.http('create-session', request);
+        return session;
+    }
+    reattachAll() {
+        for (const session of this.sessions.values()) {
+            this.core.http('create-session', session.createRequest).catch(() => {
+                /* best-effort re-attach; next user action will retry */
+            });
+        }
+    }
+    /** List sessions a namespace currently has on the server. */
+    listSessions(namespace) {
+        return this.core.http('list-sessions', { namespace: this.resolveNamespace(namespace) });
+    }
+    disconnect() {
+        this.core.disconnect();
+    }
+    // ---- internal session plumbing -----------------------------------------
+    /** @internal */
+    _emitInput(sessionId, data) {
+        this.core.emit('input', { sessionId, data });
+    }
+    /** @internal */
+    _resize(sessionId, cols, rows) {
+        return this.core.http('resize', { sessionId, cols, rows }).then(() => undefined);
+    }
+    /** @internal */
+    _cancel(sessionId) {
+        return this.core.http('cancel', { sessionId }).then(() => undefined);
+    }
+    /** @internal */
+    _clear(sessionId) {
+        return this.core.http('clear', { sessionId }).then(() => undefined);
+    }
+    /** @internal */
+    _kill(sessionId) {
+        return this.core.http('kill-session', { sessionId }).then(() => {
+            this.sessions.delete(sessionId);
+        });
+    }
+    /** @internal */
+    _forget(sessionId) {
+        this.sessions.delete(sessionId);
+    }
+}
+//# sourceMappingURL=pty-kit-client.js.map

package/dist/client/pty-kit-client.js.map

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

package/dist/client/terminal.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `mountTerminal` — a ready-to-use xterm.js terminal wired to a PtyKit session.
+ *
+ * The framework-agnostic counterpart to `<PtyTerminal/>`: hand it a container
+ * element and a `url` and you get back a live, fitted terminal — no manual
+ * `new Terminal()`, `loadAddon`, `open`, or `onData` plumbing. It stays fully
+ * configurable (appearance, theme, an existing client, callbacks) and returns a
+ * handle with the underlying `terminal`/`fitAddon`/`session` for advanced use.
+ *
+ * xterm and the FitAddon are imported dynamically (they are optional peer deps),
+ * so non-browser/headless consumers of `ptykit/client` never pull them in, and
+ * the call is SSR-safe — it only touches the DOM when actually invoked.
+ */
+import { PtyKitClient, type ClientSession } from './pty-kit-client.js';
+import type { ReconnectOptions, WSStatus } from './ws-core.js';
+import type { SessionPersistence } from './persistence.js';
+export interface MountTerminalOptions {
+    /** WebSocket endpoint, e.g. `/pty` or `wss://host/pty`. */
+    url: string;
+    /** Session to attach to / create. Omit when creating to auto-generate one. */
+    sessionId?: string;
+    /** Room/namespace. Required (here or on a passed-in `client`). */
+    namespace?: string;
+    /** Create a new session instead of attaching. Default `false`. */
+    create?: boolean;
+    /** Reuse an existing client (e.g. to share one socket across terminals). */
+    client?: PtyKitClient;
+    /** Reconnect tuning for the internally-created client. */
+    reconnect?: ReconnectOptions;
+    /** sessionId persistence override. */
+    persistence?: SessionPersistence;
+    /** RPC timeout (ms). */
+    requestTimeoutMs?: number;
+    cols?: number;
+    rows?: number;
+    cwd?: string;
+    shell?: string;
+    scrollback?: number;
+    fontSize?: number;
+    fontFamily?: string;
+    lineHeight?: number;
+    cursorBlink?: boolean;
+    cursorStyle?: 'block' | 'underline' | 'bar';
+    /** An xterm `ITheme` object. */
+    theme?: Record<string, unknown>;
+    /** Extra/override xterm `Terminal` options. */
+    terminalOptions?: Record<string, unknown>;
+    /** Attach a FitAddon + ResizeObserver. Default `true`. */
+    fit?: boolean;
+    fitDebounceMs?: number;
+    onData?: (chunk: string) => void;
+    onExit?: (exitCode: number) => void;
+    onError?: (error: unknown) => void;
+    onStatus?: (status: WSStatus) => void;
+    onDirectory?: (directory: string) => void;
+}
+export interface TerminalHandle {
+    /** The (possibly shared) client driving the socket. */
+    client: PtyKitClient;
+    /** The attached/created session. */
+    session: ClientSession;
+    /** The xterm `Terminal` instance (typed loosely to avoid a hard xterm dep). */
+    terminal: any;
+    /** The xterm `FitAddon` instance (`undefined` when `fit: false`). */
+    fitAddon: any;
+    /** Tear everything down: detach listeners, dispose the terminal, and — if the
+     *  client was created internally — disconnect it. Idempotent. */
+    dispose(): void;
+}
+/**
+ * Mount an xterm terminal into `target`, attach/create a PtyKit session, and
+ * wire output⇄input + fit. Resolves once the session is open; rejects (and
+ * calls `onError`) if attach/create fails — so a backend/connection failure
+ * surfaces instead of leaving a silently blank terminal.
+ */
+export declare function mountTerminal(target: HTMLElement, options: MountTerminalOptions): Promise<TerminalHandle>;
+//# sourceMappingURL=terminal.d.ts.map

package/dist/client/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../../src/client/terminal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,MAAM,WAAW,oBAAoB;IAEpC,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,sCAAsC;IACtC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,wBAAwB;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAG1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,GAAG,WAAW,GAAG,KAAK,CAAC;IAC5C,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAG1C,0DAA0D;IAC1D,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IAGvB,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,KAAK,IAAI,CAAC;IACtC,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1C;AAED,MAAM,WAAW,cAAc;IAC9B,uDAAuD;IACvD,MAAM,EAAE,YAAY,CAAC;IACrB,oCAAoC;IACpC,OAAO,EAAE,aAAa,CAAC;IACvB,+EAA+E;IAC/E,QAAQ,EAAE,GAAG,CAAC;IACd,qEAAqE;IACrE,QAAQ,EAAE,GAAG,CAAC;IACd;qEACiE;IACjE,OAAO,IAAI,IAAI,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAClC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,oBAAoB,GAC3B,OAAO,CAAC,cAAc,CAAC,CAyFzB"}

package/dist/client/terminal.js

@@ -0,0 +1,112 @@
+/**
+ * `mountTerminal` — a ready-to-use xterm.js terminal wired to a PtyKit session.
+ *
+ * The framework-agnostic counterpart to `<PtyTerminal/>`: hand it a container
+ * element and a `url` and you get back a live, fitted terminal — no manual
+ * `new Terminal()`, `loadAddon`, `open`, or `onData` plumbing. It stays fully
+ * configurable (appearance, theme, an existing client, callbacks) and returns a
+ * handle with the underlying `terminal`/`fitAddon`/`session` for advanced use.
+ *
+ * xterm and the FitAddon are imported dynamically (they are optional peer deps),
+ * so non-browser/headless consumers of `ptykit/client` never pull them in, and
+ * the call is SSR-safe — it only touches the DOM when actually invoked.
+ */
+import { PtyKitClient } from './pty-kit-client.js';
+import { attachFit } from './fit.js';
+/**
+ * Mount an xterm terminal into `target`, attach/create a PtyKit session, and
+ * wire output⇄input + fit. Resolves once the session is open; rejects (and
+ * calls `onError`) if attach/create fails — so a backend/connection failure
+ * surfaces instead of leaving a silently blank terminal.
+ */
+export async function mountTerminal(target, options) {
+    // Optional peer deps, loaded lazily so the core client stays xterm-free.
+    const [{ Terminal }, { FitAddon }] = (await Promise.all([
+        import('@xterm/xterm'),
+        import('@xterm/addon-fit'),
+    ]));
+    const terminal = new Terminal({
+        scrollback: options.scrollback ?? 5000,
+        fontSize: options.fontSize ?? 13,
+        fontFamily: options.fontFamily ?? 'ui-monospace, SFMono-Regular, Menlo, monospace',
+        lineHeight: options.lineHeight ?? 1.0,
+        cursorBlink: options.cursorBlink ?? true,
+        cursorStyle: options.cursorStyle ?? 'block',
+        allowProposedApi: true,
+        ...(options.theme ? { theme: options.theme } : {}),
+        ...(options.terminalOptions ?? {}),
+    });
+    const fitAddon = options.fit === false ? undefined : new FitAddon();
+    if (fitAddon)
+        terminal.loadAddon(fitAddon);
+    terminal.open(target);
+    const ownClient = !options.client;
+    const client = options.client ??
+        new PtyKitClient({
+            url: options.url,
+            namespace: options.namespace,
+            reconnect: options.reconnect,
+            persistence: options.persistence,
+            requestTimeoutMs: options.requestTimeoutMs,
+        });
+    const unsubs = [];
+    if (options.onStatus)
+        unsubs.push(client.onStatus(options.onStatus));
+    const open = {
+        sessionId: options.sessionId,
+        namespace: options.namespace,
+        cols: options.cols ?? terminal.cols,
+        rows: options.rows ?? terminal.rows,
+        cwd: options.cwd,
+        shell: options.shell,
+    };
+    let session;
+    try {
+        session = options.create
+            ? await client.create(open)
+            : await client.attach(options.sessionId, open);
+    }
+    catch (err) {
+        for (const u of unsubs)
+            u();
+        terminal.dispose();
+        if (ownClient)
+            client.disconnect();
+        options.onError?.(err);
+        throw err;
+    }
+    unsubs.push(session.onData((chunk) => {
+        terminal.write(chunk);
+        options.onData?.(chunk);
+    }));
+    if (options.onExit)
+        unsubs.push(session.onExit(options.onExit));
+    if (options.onError)
+        unsubs.push(session.onError(options.onError));
+    if (options.onDirectory)
+        unsubs.push(session.onDirectory(options.onDirectory));
+    terminal.onData((data) => session.write(data));
+    const detachFit = fitAddon
+        ? attachFit(session, terminal, fitAddon, { debounceMs: options.fitDebounceMs ?? 100 })
+        : undefined;
+    let disposed = false;
+    return {
+        client,
+        session,
+        terminal,
+        fitAddon,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            detachFit?.();
+            for (const u of unsubs)
+                u();
+            session.detach();
+            terminal.dispose();
+            if (ownClient)
+                client.disconnect();
+        },
+    };
+}
+//# sourceMappingURL=terminal.js.map

package/dist/client/terminal.js.map

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

package/dist/client/ws-core.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Resilient WebSocket client core — the battle-tested pieces of a production
+ * WebSocket client:
+ *  - exponential backoff reconnect (default 1s→30s, max 5 attempts),
+ *  - **heal-reconnect** for "open but dead" sockets (a stalled read forces one
+ *    reconnect + retry before failing),
+ *  - **idempotency-aware resend**: reads resend freely; mutations resend only if
+ *    never actually delivered,
+ *  - `onReconnect` fires BEFORE the queue flush so room re-subscription happens
+ *    first,
+ *  - connection status surfaced via `onStatus`.
+ *
+ * Text/JSON frames only (terminal I/O is text). The WebSocket implementation is
+ * injectable for testing.
+ */
+import { type Seq } from '../shared/index.js';
+export type WSStatus = 'connected' | 'reconnecting' | 'disconnected';
+/** Minimal structural WebSocket shape (browser `WebSocket` satisfies it). */
+export interface WebSocketLike {
+    readyState: number;
+    send(data: string): void;
+    close(): void;
+    onopen: ((ev?: any) => void) | null;
+    onmessage: ((ev: {
+        data: any;
+    }) => void) | null;
+    onclose: ((ev?: any) => void) | null;
+    onerror: ((ev?: any) => void) | null;
+}
+export type WebSocketFactory = (url: string) => WebSocketLike;
+export interface ReconnectOptions {
+    enabled?: boolean;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    /** 0 = infinite. Default 5. */
+    maxAttempts?: number;
+}
+export interface WsCoreOptions {
+    url: string;
+    reconnect?: ReconnectOptions;
+    onStatus?: (status: WSStatus, attempts: number) => void;
+    /** Fired on every reconnect (not the first connect), before the queue flush. */
+    onReconnect?: () => void;
+    /** Injectable WebSocket constructor (defaults to global `WebSocket`). */
+    WebSocketImpl?: WebSocketFactory;
+    /** RPC timeout (ms). Default 30000. */
+    requestTimeoutMs?: number;
+}
+export declare class WsCore {
+    private ws;
+    private readonly url;
+    private readonly factory;
+    private readonly reconnectOpts;
+    private readonly requestTimeoutMs;
+    private readonly onStatus?;
+    private readonly onReconnect?;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private isConnected;
+    private shouldReconnect;
+    private hasConnectedBefore;
+    private healing;
+    private readonly listeners;
+    private messageQueue;
+    private readonly pending;
+    constructor(options: WsCoreOptions);
+    private connect;
+    private scheduleReconnect;
+    private dispatch;
+    private isSocketOpen;
+    private sendRaw;
+    /** Fire-and-forget event to the server (queued if not connected). */
+    emit(action: string, payload: unknown): void;
+    /** Subscribe to a server event. Returns an unsubscribe function. */
+    on(action: string, callback: (payload: any) => void): () => void;
+    /**
+     * RPC request/response. Resolves with the unwrapped `data` on success,
+     * rejects on error/timeout. Survives a transport hiccup (resend + heal).
+     */
+    http<TData = any>(action: string, data?: unknown, timeout?: number): Promise<TData>;
+    connected(): boolean;
+    /** Force a reconnect, preserving listeners and the pending/queue state. */
+    reconnect(): void;
+    /** Permanently disconnect and fail any in-flight requests. */
+    disconnect(): void;
+}
+export type { Seq };
+//# sourceMappingURL=ws-core.d.ts.map

package/dist/client/ws-core.d.ts.map

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