@myrialabs/ptykit 0.0.1

package/dist/client/ws-core.js

@@ -0,0 +1,324 @@
+/**
+ * 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 { RPC_ACTIONS, } from '../shared/index.js';
+const WS_OPEN = 1;
+/** RPC actions that are safe to transparently re-send after a reconnect. */
+const IDEMPOTENT_ACTIONS = new Set([
+    'create-session', // idempotent server-side (reuse by id)
+    'resize',
+    'reconnect',
+    'list-sessions',
+    'pty-status',
+    'stream-status',
+    'missed-output',
+    'check-shell',
+]);
+function isIdempotent(action) {
+    return IDEMPOTENT_ACTIONS.has(action);
+}
+export class WsCore {
+    ws = null;
+    url;
+    factory;
+    reconnectOpts;
+    requestTimeoutMs;
+    onStatus;
+    onReconnect;
+    reconnectAttempts = 0;
+    reconnectTimer = null;
+    isConnected = false;
+    shouldReconnect = true;
+    hasConnectedBefore = false;
+    healing = false;
+    listeners = new Map();
+    messageQueue = [];
+    pending = new Map();
+    constructor(options) {
+        this.url = options.url;
+        this.factory =
+            options.WebSocketImpl ?? ((url) => new WebSocket(url));
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
+        this.onStatus = options.onStatus;
+        this.onReconnect = options.onReconnect;
+        this.reconnectOpts = {
+            enabled: options.reconnect?.enabled ?? true,
+            baseDelayMs: options.reconnect?.baseDelayMs ?? 1000,
+            maxDelayMs: options.reconnect?.maxDelayMs ?? 30_000,
+            maxAttempts: options.reconnect?.maxAttempts ?? 5,
+        };
+        this.connect();
+    }
+    connect() {
+        if (this.ws) {
+            try {
+                this.ws.onclose = null;
+                this.ws.onerror = null;
+                this.ws.onmessage = null;
+                this.ws.close();
+            }
+            catch {
+                /* ignore stale socket */
+            }
+            this.ws = null;
+        }
+        const socket = this.factory(this.url);
+        this.ws = socket;
+        socket.onopen = () => {
+            this.isConnected = true;
+            this.reconnectAttempts = 0;
+            this.onStatus?.('connected', 0);
+            const isReconnect = this.hasConnectedBefore;
+            this.hasConnectedBefore = true;
+            if (isReconnect) {
+                try {
+                    this.onReconnect?.();
+                }
+                catch {
+                    /* swallow consumer error */
+                }
+            }
+            this.healing = false;
+            // Flush fire-and-forget queue (drain locally so a re-queue can't spin).
+            const queued = this.messageQueue;
+            this.messageQueue = [];
+            for (const frame of queued)
+                this.sendRaw(frame);
+            // Resend in-flight RPCs the previous socket may have swallowed.
+            for (const entry of this.pending.values()) {
+                if (entry.sent && !isIdempotent(entry.action))
+                    continue;
+                entry.sent = true;
+                this.sendRaw({ action: entry.action, payload: entry.payload });
+                entry.arm();
+            }
+        };
+        socket.onmessage = (event) => {
+            let frame;
+            try {
+                frame = JSON.parse(String(event.data));
+            }
+            catch {
+                return;
+            }
+            if (frame && typeof frame.action === 'string') {
+                this.dispatch(frame.action, frame.payload);
+            }
+        };
+        socket.onerror = () => {
+            /* errors surface via onclose */
+        };
+        socket.onclose = () => {
+            this.isConnected = false;
+            this.ws = null;
+            if (this.shouldReconnect && this.reconnectOpts.enabled) {
+                this.onStatus?.('reconnecting', this.reconnectAttempts);
+                this.scheduleReconnect();
+            }
+            else {
+                this.onStatus?.('disconnected', this.reconnectAttempts);
+            }
+        };
+    }
+    scheduleReconnect() {
+        if (this.reconnectOpts.maxAttempts > 0 &&
+            this.reconnectAttempts >= this.reconnectOpts.maxAttempts) {
+            this.onStatus?.('disconnected', this.reconnectAttempts);
+            return;
+        }
+        this.reconnectAttempts++;
+        const delay = Math.min(this.reconnectOpts.baseDelayMs * Math.pow(2, this.reconnectAttempts - 1), this.reconnectOpts.maxDelayMs);
+        this.onStatus?.('reconnecting', this.reconnectAttempts);
+        this.reconnectTimer = setTimeout(() => this.connect(), delay);
+    }
+    dispatch(action, payload) {
+        const callbacks = this.listeners.get(action);
+        if (!callbacks)
+            return;
+        for (const cb of callbacks) {
+            try {
+                cb(payload);
+            }
+            catch {
+                /* swallow listener error */
+            }
+        }
+    }
+    isSocketOpen() {
+        return !!this.ws && this.ws.readyState === WS_OPEN;
+    }
+    sendRaw(frame) {
+        if (!this.isSocketOpen()) {
+            this.messageQueue.push(frame);
+            return;
+        }
+        try {
+            this.ws.send(JSON.stringify(frame));
+        }
+        catch {
+            this.messageQueue.push(frame);
+        }
+    }
+    /** Fire-and-forget event to the server (queued if not connected). */
+    emit(action, payload) {
+        const frame = { action, payload };
+        if (this.isSocketOpen())
+            this.sendRaw(frame);
+        else
+            this.messageQueue.push(frame);
+    }
+    /** Subscribe to a server event. Returns an unsubscribe function. */
+    on(action, callback) {
+        let set = this.listeners.get(action);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(action, set);
+        }
+        set.add(callback);
+        return () => {
+            const s = this.listeners.get(action);
+            if (s) {
+                s.delete(callback);
+                if (s.size === 0)
+                    this.listeners.delete(action);
+            }
+        };
+    }
+    /**
+     * RPC request/response. Resolves with the unwrapped `data` on success,
+     * rejects on error/timeout. Survives a transport hiccup (resend + heal).
+     */
+    http(action, data = {}, timeout = this.requestTimeoutMs) {
+        if (!RPC_ACTIONS.includes(action)) {
+            return Promise.reject(new Error(`Unknown RPC action: ${action}`));
+        }
+        const requestId = `${action}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+        const payload = { requestId, data };
+        const responseAction = `${action}:response`;
+        const idempotent = isIdempotent(action);
+        const MAX_HEAL = 2;
+        return new Promise((resolve, reject) => {
+            let unsub = null;
+            let timer = null;
+            const entry = {
+                action,
+                payload,
+                sent: false,
+                attempts: 0,
+                arm: () => {
+                    if (timeout <= 0)
+                        return;
+                    if (timer)
+                        clearTimeout(timer);
+                    timer = setTimeout(onTimeout, timeout);
+                },
+                cleanup: () => {
+                    unsub?.();
+                    if (timer)
+                        clearTimeout(timer);
+                    timer = null;
+                    this.pending.delete(requestId);
+                },
+                fail: (err) => {
+                    entry.cleanup();
+                    reject(err);
+                },
+            };
+            const onTimeout = () => {
+                if (idempotent && entry.attempts < MAX_HEAL) {
+                    entry.attempts++;
+                    entry.arm();
+                    // Socket claims open but stalled → likely black-holed; force a
+                    // reconnect (guarded). The onopen resend loop re-delivers this.
+                    if (this.isSocketOpen() && !this.healing) {
+                        this.healing = true;
+                        this.reconnect();
+                    }
+                    return;
+                }
+                entry.cleanup();
+                reject(new Error(`Request timeout: ${action} (${timeout}ms)`));
+            };
+            const handleResponse = (response) => {
+                if (response?.requestId !== requestId)
+                    return;
+                entry.cleanup();
+                if (response.success)
+                    resolve(response.data);
+                else
+                    reject(new Error(response.error || 'Unknown error'));
+            };
+            unsub = this.on(responseAction, handleResponse);
+            this.pending.set(requestId, entry);
+            entry.arm();
+            if (this.isSocketOpen()) {
+                entry.sent = true;
+                this.sendRaw({ action, payload });
+            }
+        });
+    }
+    connected() {
+        return this.isConnected;
+    }
+    /** Force a reconnect, preserving listeners and the pending/queue state. */
+    reconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            try {
+                this.ws.onclose = null;
+                this.ws.onerror = null;
+                this.ws.onmessage = null;
+                this.ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+            this.ws = null;
+        }
+        this.isConnected = false;
+        this.shouldReconnect = true;
+        this.reconnectAttempts = 0;
+        this.connect();
+    }
+    /** Permanently disconnect and fail any in-flight requests. */
+    disconnect() {
+        this.shouldReconnect = false;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            try {
+                this.ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+            this.ws = null;
+        }
+        this.listeners.clear();
+        this.messageQueue = [];
+        this.isConnected = false;
+        for (const entry of [...this.pending.values()]) {
+            entry.fail(new Error('WebSocket disconnected'));
+        }
+        this.pending.clear();
+        this.onStatus?.('disconnected', this.reconnectAttempts);
+    }
+}
+//# sourceMappingURL=ws-core.js.map

package/dist/client/ws-core.js.map

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

package/dist/core/backend.d.ts

@@ -0,0 +1,52 @@
+/**
+ * PTY backend abstraction.
+ *
+ * Both supported backends — `bun-pty` (tested) and `node-pty` (experimental) —
+ * expose a near-identical `IPty` surface (`spawn(file, args, opts) → handle`
+ * with `onData`/`onExit`/`write`/`resize`/`kill`/`pid`/`cols`/`rows`). This
+ * interface is the thin common shape the rest of the core depends on, so the
+ * session engine never imports a backend directly.
+ */
+/** A disposable event subscription. */
+export interface PtyDisposable {
+    dispose(): void;
+}
+/** PTY process exit event. */
+export interface PtyExitEvent {
+    exitCode: number;
+    signal?: number | string;
+}
+/** Options for spawning a PTY. */
+export interface PtySpawnOptions {
+    /** Terminal name set in the child env. Defaults to `xterm-256color`. */
+    name?: string;
+    cols: number;
+    rows: number;
+    cwd: string;
+    env: Record<string, string>;
+}
+/** A live PTY process handle, normalized across backends. */
+export interface PtyProcessHandle {
+    readonly pid: number;
+    readonly cols: number;
+    readonly rows: number;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    kill(signal?: string): void;
+    onData(listener: (data: string) => void): PtyDisposable;
+    onExit(listener: (event: PtyExitEvent) => void): PtyDisposable;
+}
+/** Backend identifier. */
+export type PtyBackendName = 'bun-pty' | 'node-pty';
+/** A PTY backend: spawns processes and reports its support status. */
+export interface PtyBackend {
+    readonly name: PtyBackendName;
+    /**
+     * `true` while the backend has not yet been gated to "supported" by the
+     * scale and auto-detect benchmarks. `node-pty` is experimental; `bun-pty` is
+     * the tested path.
+     */
+    readonly experimental: boolean;
+    spawn(file: string, args: string[], options: PtySpawnOptions): PtyProcessHandle;
+}
+//# sourceMappingURL=backend.d.ts.map

package/dist/core/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/core/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC7B,OAAO,IAAI,IAAI,CAAC;CAChB;AAED,8BAA8B;AAC9B,MAAM,WAAW,YAAY;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED,kCAAkC;AAClC,MAAM,WAAW,eAAe;IAC/B,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5B;AAED,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,aAAa,CAAC;IACxD,MAAM,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,aAAa,CAAC;CAC/D;AAED,0BAA0B;AAC1B,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,CAAC;AAEpD,sEAAsE;AACtE,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,eAAe,GAAG,gBAAgB,CAAC;CAChF"}

package/dist/core/backend.js

@@ -0,0 +1,11 @@
+/**
+ * PTY backend abstraction.
+ *
+ * Both supported backends — `bun-pty` (tested) and `node-pty` (experimental) —
+ * expose a near-identical `IPty` surface (`spawn(file, args, opts) → handle`
+ * with `onData`/`onExit`/`write`/`resize`/`kill`/`pid`/`cols`/`rows`). This
+ * interface is the thin common shape the rest of the core depends on, so the
+ * session engine never imports a backend directly.
+ */
+export {};
+//# sourceMappingURL=backend.js.map

package/dist/core/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/core/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/core/detect.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Runtime detection + lazy backend loading.
+ *
+ * The PTY backend is an OPTIONAL dependency resolved at runtime via dynamic
+ * `import()`: `bun-pty` under Bun (tested), `node-pty` under Node (experimental).
+ * Importing lazily means a Node consumer never builds `bun-pty` (rust/ffi) and a
+ * Bun consumer never builds `node-pty`.
+ */
+import type { PtyBackend, PtyBackendName } from './backend.js';
+/** True when running under Bun. */
+export declare function isBun(): boolean;
+/** The backend that auto-detect will pick for the current runtime. */
+export declare function detectBackendName(): PtyBackendName;
+/**
+ * Load the PTY backend for the current runtime (or a forced one).
+ * The result is cached process-wide.
+ */
+export declare function loadBackend(prefer?: PtyBackendName): Promise<PtyBackend>;
+/** Reset the cached backend (used by tests). */
+export declare function resetBackendCache(): void;
+//# sourceMappingURL=detect.d.ts.map

package/dist/core/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../src/core/detect.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACX,UAAU,EACV,cAAc,EAGd,MAAM,cAAc,CAAC;AAkBtB,mCAAmC;AACnC,wBAAgB,KAAK,IAAI,OAAO,CAK/B;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,IAAI,cAAc,CAElD;AAyCD;;;GAGG;AACH,wBAAsB,WAAW,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAyB9E;AAED,gDAAgD;AAChD,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}

package/dist/core/detect.js

@@ -0,0 +1,82 @@
+/**
+ * Runtime detection + lazy backend loading.
+ *
+ * The PTY backend is an OPTIONAL dependency resolved at runtime via dynamic
+ * `import()`: `bun-pty` under Bun (tested), `node-pty` under Node (experimental).
+ * Importing lazily means a Node consumer never builds `bun-pty` (rust/ffi) and a
+ * Bun consumer never builds `node-pty`.
+ */
+/** True when running under Bun. */
+export function isBun() {
+    return (typeof globalThis.Bun !== 'undefined' ||
+        typeof process?.versions?.bun === 'string');
+}
+/** The backend that auto-detect will pick for the current runtime. */
+export function detectBackendName() {
+    return isBun() ? 'bun-pty' : 'node-pty';
+}
+/** Wrap a backend's raw PTY into the normalized handle. */
+function wrapPty(raw) {
+    return {
+        get pid() {
+            return raw.pid;
+        },
+        get cols() {
+            return raw.cols;
+        },
+        get rows() {
+            return raw.rows;
+        },
+        write: (data) => raw.write(data),
+        resize: (cols, rows) => raw.resize(cols, rows),
+        kill: (signal) => raw.kill(signal),
+        onData: (listener) => raw.onData(listener),
+        onExit: (listener) => raw.onExit(listener),
+    };
+}
+function makeBackend(name, spawn) {
+    return {
+        name,
+        experimental: name === 'node-pty',
+        spawn(file, args, options) {
+            const raw = spawn(file, args, {
+                name: options.name ?? 'xterm-256color',
+                cols: options.cols,
+                rows: options.rows,
+                cwd: options.cwd,
+                env: options.env,
+            });
+            return wrapPty(raw);
+        },
+    };
+}
+let cached = null;
+/**
+ * Load the PTY backend for the current runtime (or a forced one).
+ * The result is cached process-wide.
+ */
+export async function loadBackend(prefer) {
+    if (cached && (!prefer || cached.name === prefer))
+        return cached;
+    const name = prefer ?? detectBackendName();
+    const moduleName = name; // 'bun-pty' | 'node-pty'
+    let mod;
+    try {
+        mod = await import(/* @vite-ignore */ moduleName);
+    }
+    catch (err) {
+        throw new Error(`ptykit: failed to load the "${moduleName}" PTY backend. Install it for this runtime ` +
+            `(\`${isBun() ? 'bun add' : 'npm install'} ${moduleName}\`). Underlying error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const spawn = mod?.spawn ?? mod?.default?.spawn;
+    if (typeof spawn !== 'function') {
+        throw new Error(`ptykit: "${moduleName}" did not export a spawn() function.`);
+    }
+    cached = makeBackend(name, spawn);
+    return cached;
+}
+/** Reset the cached backend (used by tests). */
+export function resetBackendCache() {
+    cached = null;
+}
+//# sourceMappingURL=detect.js.map

package/dist/core/detect.js.map

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

package/dist/core/env.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Environment hygiene (R2).
+ *
+ * Spawning a shell from inside a Bun/npm/Vite process leaks the runtime's own
+ * pollution into the child (npm_*, VITE_*, a `node_modules/.bin` PATH, etc.),
+ * which breaks version managers and confuses interactive shells. We strip that
+ * pollution, then inject the terminal-friendly variables xterm.js expects.
+ */
+/** Env hygiene configuration. */
+export interface EnvOptions {
+    /** Strip Bun/npm/Vite runtime pollution from `process.env`. Default `true`. */
+    sanitize?: boolean;
+    /**
+     * Variables injected/overridden after sanitizing. Merged over the terminal
+     * defaults (`FORCE_COLOR`, `COLORTERM`, `TERM`, `TERM_PROGRAM`, `CLICOLOR`,
+     * `LC_ALL`, `LANG`). `COLUMNS`/`LINES` are always set from the PTY size.
+     */
+    inject?: Record<string, string>;
+}
+/** Build a clean copy of `process.env` for spawning a child shell. */
+export declare function getCleanSpawnEnv(): Record<string, string>;
+/**
+ * Produce the environment for a PTY: sanitized base (optional) plus the
+ * terminal-specific variables xterm.js relies on, with caller overrides last.
+ */
+export declare function buildPtyEnv(options: EnvOptions | undefined, size: {
+    cols: number;
+    rows: number;
+}): Record<string, string>;
+//# sourceMappingURL=env.d.ts.map

package/dist/core/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/core/env.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,iCAAiC;AACjC,MAAM,WAAW,UAAU;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAsBD,sEAAsE;AACtE,wBAAgB,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUzD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAC1B,OAAO,EAAE,UAAU,GAAG,SAAS,EAC/B,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAwBxB"}

package/dist/core/env.js

@@ -0,0 +1,68 @@
+/**
+ * Environment hygiene (R2).
+ *
+ * Spawning a shell from inside a Bun/npm/Vite process leaks the runtime's own
+ * pollution into the child (npm_*, VITE_*, a `node_modules/.bin` PATH, etc.),
+ * which breaks version managers and confuses interactive shells. We strip that
+ * pollution, then inject the terminal-friendly variables xterm.js expects.
+ */
+/** Env-var name prefixes always injected by Bun/npm/Vite. */
+const FILTERED_PREFIXES = ['npm_', 'VITE_'];
+/** Specific var names injected by the runtime. */
+const FILTERED_NAMES = new Set(['_BUN_WATCHER_CHILD']);
+/** Remove `node_modules/.bin`-style entries from PATH. */
+function cleanPath(env) {
+    const isWindows = process.platform === 'win32';
+    const pathKey = isWindows ? (env.Path !== undefined ? 'Path' : 'PATH') : 'PATH';
+    const value = env[pathKey];
+    if (value) {
+        const sep = isWindows ? ';' : ':';
+        env[pathKey] = value
+            .split(sep)
+            .filter((p) => !p.includes('node_modules'))
+            .join(sep);
+    }
+}
+/** Build a clean copy of `process.env` for spawning a child shell. */
+export function getCleanSpawnEnv() {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value === undefined)
+            continue;
+        if (FILTERED_NAMES.has(key))
+            continue;
+        if (FILTERED_PREFIXES.some((p) => key.startsWith(p)))
+            continue;
+        env[key] = value;
+    }
+    cleanPath(env);
+    return env;
+}
+/**
+ * Produce the environment for a PTY: sanitized base (optional) plus the
+ * terminal-specific variables xterm.js relies on, with caller overrides last.
+ */
+export function buildPtyEnv(options, size) {
+    const sanitize = options?.sanitize ?? true;
+    const base = sanitize
+        ? getCleanSpawnEnv()
+        : { ...process.env };
+    const terminalDefaults = {
+        FORCE_COLOR: '1',
+        COLORTERM: 'truecolor',
+        TERM: 'xterm-256color',
+        TERM_PROGRAM: 'xterm.js',
+        CLICOLOR: '1',
+        LC_ALL: 'en_US.UTF-8',
+        LANG: 'en_US.UTF-8',
+    };
+    return {
+        ...base,
+        ...terminalDefaults,
+        ...(options?.inject ?? {}),
+        // Size always reflects the actual PTY dimensions, regardless of injects.
+        COLUMNS: String(size.cols),
+        LINES: String(size.rows),
+    };
+}
+//# sourceMappingURL=env.js.map

package/dist/core/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/core/env.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAcH,6DAA6D;AAC7D,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5C,kDAAkD;AAClD,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC;AAEvD,0DAA0D;AAC1D,SAAS,SAAS,CAAC,GAA2B;IAC7C,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC;IAC/C,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAChF,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3B,IAAI,KAAK,EAAE,CAAC;QACX,MAAM,GAAG,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;QAClC,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK;aAClB,KAAK,CAAC,GAAG,CAAC;aACV,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;aAC1C,IAAI,CAAC,GAAG,CAAC,CAAC;IACb,CAAC;AACF,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,gBAAgB;IAC/B,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACxD,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,IAAI,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QACtC,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YAAE,SAAS;QAC/D,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAClB,CAAC;IACD,SAAS,CAAC,GAAG,CAAC,CAAC;IACf,OAAO,GAAG,CAAC;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAC1B,OAA+B,EAC/B,IAAoC;IAEpC,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,IAAI,CAAC;IAC3C,MAAM,IAAI,GAAG,QAAQ;QACpB,CAAC,CAAC,gBAAgB,EAAE;QACpB,CAAC,CAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAA6B,CAAC;IAElD,MAAM,gBAAgB,GAA2B;QAChD,WAAW,EAAE,GAAG;QAChB,SAAS,EAAE,WAAW;QACtB,IAAI,EAAE,gBAAgB;QACtB,YAAY,EAAE,UAAU;QACxB,QAAQ,EAAE,GAAG;QACb,MAAM,EAAE,aAAa;QACrB,IAAI,EAAE,aAAa;KACnB,CAAC;IAEF,OAAO;QACN,GAAG,IAAI;QACP,GAAG,gBAAgB;QACnB,GAAG,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,CAAC;QAC1B,yEAAyE;QACzE,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;QAC1B,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;KACxB,CAAC;AACH,CAAC"}

package/dist/core/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Core PTY session engine — barrel.
+ */
+export type { PtyBackend, PtyBackendName, PtyProcessHandle, PtySpawnOptions, PtyExitEvent, PtyDisposable, } from './backend.js';
+export { detectBackendName, isBun, loadBackend, resetBackendCache } from './detect.js';
+export { buildPtyEnv, getCleanSpawnEnv, type EnvOptions } from './env.js';
+export { checkShell, isWindows, resolveCwd, resolveShell, type ShellInvocation } from './shell.js';
+export { MemoryBufferStore, type BufferStore } from './scrollback.js';
+export { Session, type SessionConfig, type SessionInfo, type SessionDataListener, type SessionExitListener, } from './session.js';
+export { PtyKit, type PtyKitOptions, type CreateSessionOptions, } from './pty-kit.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EACX,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,aAAa,GACb,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,iBAAiB,EAAE,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACvF,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AACnG,OAAO,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EACN,OAAO,EACP,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACxB,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,MAAM,EACN,KAAK,aAAa,EAClB,KAAK,oBAAoB,GACzB,MAAM,cAAc,CAAC"}