@myrialabs/ptykit 0.0.1

package/dist/shared/index.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Shared wire-protocol types and primitives used across the core engine, the
+ * WebSocket transport, and the browser client.
+ *
+ * The transport is a single multiplexed WebSocket. Two planes ride it:
+ *  - **Control plane** — RPC request/response keyed by `requestId`.
+ *  - **Data plane** — broadcast events fanned out to a room and filtered
+ *    client-side by `sessionId`.
+ */
+/** PtyKit package version. */
+export declare const PTYKIT_VERSION = "0.1.0";
+/**
+ * Monotonic sequence number stamped on every output event so clients can
+ * deduplicate replayed-vs-live output after a reattach (R5).
+ */
+export type Seq = number;
+/**
+ * Every WebSocket message is a JSON frame `{ action, payload }`. RPC requests
+ * carry `payload = { requestId, data }`; RPC responses use action
+ * `${action}:response` with `payload = { requestId, success, data?, error? }`;
+ * events carry their event payload directly.
+ */
+export interface WireFrame {
+    action: string;
+    payload: unknown;
+}
+/** RPC request payload. */
+export interface RpcRequest<D = unknown> {
+    requestId: string;
+    data: D;
+}
+/** RPC response payload. The client unwraps `data` on success, throws on failure. */
+export interface RpcResponse<D = unknown> {
+    requestId: string;
+    success: boolean;
+    data?: D;
+    error?: string;
+}
+/** Operation names (control plane). */
+export declare const RPC_ACTIONS: readonly ["create-session", "resize", "cancel", "kill-session", "clear", "check-shell", "pty-status", "list-sessions", "stream-status", "missed-output", "reconnect"];
+export type RpcAction = (typeof RPC_ACTIONS)[number];
+/** Fire-and-forget client→server events (data plane in). */
+export declare const CLIENT_EVENTS: readonly ["input"];
+export type ClientEvent = (typeof CLIENT_EVENTS)[number];
+/** Server→client broadcast events (data plane out). */
+export declare const SERVER_EVENTS: readonly ["ready", "output", "directory", "exit", "error", "tab-created", "tab-closed"];
+export type ServerEvent = (typeof SERVER_EVENTS)[number];
+export interface CreateSessionRequest {
+    sessionId: string;
+    namespace: string;
+    streamId?: string;
+    shell?: string;
+    cwd?: string;
+    cols?: number;
+    rows?: number;
+}
+export interface CreateSessionResponse {
+    sessionId: string;
+    streamId: string;
+    pid: number;
+    currentDirectory: string;
+    cols: number;
+    rows: number;
+}
+export interface ResizeRequest {
+    sessionId: string;
+    cols: number;
+    rows: number;
+}
+export interface ResizeResponse {
+    sessionId: string;
+    cols: number;
+    rows: number;
+}
+export interface CancelRequest {
+    sessionId: string;
+}
+export interface CancelResponse {
+    sessionId: string;
+    pid: number;
+}
+export interface KillSessionRequest {
+    sessionId: string;
+}
+export interface KillSessionResponse {
+    sessionId: string;
+    pid?: number;
+}
+export interface ClearRequest {
+    sessionId: string;
+}
+export interface ClearResponse {
+    sessionId: string;
+}
+export interface CheckShellRequest {
+    namespace?: string;
+}
+export interface CheckShellResponse {
+    available: boolean;
+    path: string | null;
+    platform: string;
+    isWindows: boolean;
+    shellType: string;
+}
+export interface PtyStatusRequest {
+    sessionId: string;
+}
+export interface PtyStatusResponse {
+    isActive: boolean;
+    sessionId: string;
+    pid?: number;
+    message?: string;
+}
+export interface ListSessionsRequest {
+    namespace: string;
+}
+export interface ListedSession {
+    sessionId: string;
+    pid: number;
+    cwd: string;
+    createdAt: string;
+    lastActivityAt: string;
+}
+export interface ListSessionsResponse {
+    sessions: ListedSession[];
+}
+export interface StreamStatusRequest {
+    sessionId: string;
+}
+export interface StreamStatusResponse {
+    status: string;
+    bufferLength: number;
+    startedAt: string;
+    processId?: number;
+}
+export interface MissedOutputRequest {
+    sessionId: string;
+}
+export interface MissedOutputResponse {
+    sessionId: string;
+    output: string;
+    status: string;
+    timestamp: string;
+}
+export interface ReconnectRequest {
+    sessionId: string;
+}
+export interface ReconnectResponse {
+    sessionId: string;
+    output: string;
+    status: string;
+}
+/** Maps each RPC action to its `{ data, response }` contract. */
+export interface RpcMap {
+    'create-session': {
+        data: CreateSessionRequest;
+        response: CreateSessionResponse;
+    };
+    resize: {
+        data: ResizeRequest;
+        response: ResizeResponse;
+    };
+    cancel: {
+        data: CancelRequest;
+        response: CancelResponse;
+    };
+    'kill-session': {
+        data: KillSessionRequest;
+        response: KillSessionResponse;
+    };
+    clear: {
+        data: ClearRequest;
+        response: ClearResponse;
+    };
+    'check-shell': {
+        data: CheckShellRequest;
+        response: CheckShellResponse;
+    };
+    'pty-status': {
+        data: PtyStatusRequest;
+        response: PtyStatusResponse;
+    };
+    'list-sessions': {
+        data: ListSessionsRequest;
+        response: ListSessionsResponse;
+    };
+    'stream-status': {
+        data: StreamStatusRequest;
+        response: StreamStatusResponse;
+    };
+    'missed-output': {
+        data: MissedOutputRequest;
+        response: MissedOutputResponse;
+    };
+    reconnect: {
+        data: ReconnectRequest;
+        response: ReconnectResponse;
+    };
+}
+export interface InputEvent {
+    sessionId: string;
+    data: string;
+}
+export interface ReadyEvent {
+    sessionId: string;
+    streamId: string;
+    pid: number;
+    cols: number;
+    rows: number;
+}
+export interface OutputEvent {
+    sessionId: string;
+    content: string;
+    seq?: Seq;
+    timestamp: string;
+}
+export interface DirectoryEvent {
+    sessionId: string;
+    newDirectory: string;
+}
+export interface ExitEvent {
+    sessionId: string;
+    exitCode: number;
+}
+export interface ErrorEvent {
+    sessionId: string;
+    error: string;
+}
+export interface TabCreatedEvent {
+    sessionId: string;
+    streamId: string;
+    pid: number;
+    currentDirectory: string;
+    cols: number;
+    rows: number;
+}
+export interface TabClosedEvent {
+    sessionId: string;
+}
+/** Maps each server→client event to its payload. */
+export interface ServerEventMap {
+    ready: ReadyEvent;
+    output: OutputEvent;
+    directory: DirectoryEvent;
+    exit: ExitEvent;
+    error: ErrorEvent;
+    'tab-created': TabCreatedEvent;
+    'tab-closed': TabClosedEvent;
+}
+/** Strip terminal report-request sequences from replayed content (R17). */
+export declare function stripReportRequests(content: string): string;
+/** Minimal logger interface. The library never writes to stdout/stderr itself. */
+export interface Logger {
+    log(scope: string, ...args: unknown[]): void;
+    warn(scope: string, ...args: unknown[]): void;
+    error(scope: string, ...args: unknown[]): void;
+}
+/** A logger that discards everything — the default. */
+export declare const silentLogger: Logger;
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/shared/index.js

@@ -0,0 +1,85 @@
+/**
+ * Shared wire-protocol types and primitives used across the core engine, the
+ * WebSocket transport, and the browser client.
+ *
+ * The transport is a single multiplexed WebSocket. Two planes ride it:
+ *  - **Control plane** — RPC request/response keyed by `requestId`.
+ *  - **Data plane** — broadcast events fanned out to a room and filtered
+ *    client-side by `sessionId`.
+ */
+/** PtyKit package version. */
+export const PTYKIT_VERSION = '0.1.0';
+// ============================================================================
+// Control-plane operations (RPC)
+// ============================================================================
+/** Operation names (control plane). */
+export const RPC_ACTIONS = [
+    'create-session',
+    'resize',
+    'cancel',
+    'kill-session',
+    'clear',
+    'check-shell',
+    'pty-status',
+    'list-sessions',
+    'stream-status',
+    'missed-output',
+    'reconnect',
+];
+/** Fire-and-forget client→server events (data plane in). */
+export const CLIENT_EVENTS = ['input'];
+/** Server→client broadcast events (data plane out). */
+export const SERVER_EVENTS = [
+    'ready',
+    'output',
+    'directory',
+    'exit',
+    'error',
+    'tab-created',
+    'tab-closed',
+];
+// ============================================================================
+// Replay hygiene (R17)
+// ============================================================================
+/**
+ * Escape sequences that ask the terminal to *report back* (color, cursor
+ * position, device attributes, mode/status). They are emitted by shells and
+ * TUI apps (powerlevel10k, starship, vim) and get captured raw into stored
+ * session output.
+ *
+ * During live output these must reach xterm so it can answer the program
+ * waiting to read the reply. But when REPLAYING stored history no program is
+ * waiting — xterm still answers via `onData`, and that answer gets forwarded to
+ * the live PTY and printed at the idle shell prompt. So we strip these requests
+ * from replayed content only.
+ */
+/* eslint-disable no-control-regex -- these patterns deliberately match ANSI escape (ESC) sequences */
+const REPORT_REQUEST_PATTERNS = [
+    // OSC color query: ESC ] <ps> ; ? (BEL | ST)
+    /\x1b\][0-9;]*\?(?:\x07|\x1b\\)/g,
+    // Device Status Report / cursor position request: ESC [ ?? <ps> n
+    /\x1b\[\??[0-9;]*n/g,
+    // Device Attributes: ESC [ [<=>]? <ps> c
+    /\x1b\[[<=>]?[0-9;]*c/g,
+    // DECRQM mode query: ESC [ ? <ps> $ p
+    /\x1b\[\?[0-9;]*\$p/g,
+    // DECRQSS status string request (DCS): ESC P <ps> $ q ... ESC \
+    /\x1bP[0-9;]*\$q[\s\S]*?\x1b\\/g,
+];
+/* eslint-enable no-control-regex */
+/** Strip terminal report-request sequences from replayed content (R17). */
+export function stripReportRequests(content) {
+    let result = content;
+    for (const pattern of REPORT_REQUEST_PATTERNS) {
+        pattern.lastIndex = 0;
+        result = result.replace(pattern, '');
+    }
+    return result;
+}
+/** A logger that discards everything — the default. */
+export const silentLogger = {
+    log() { },
+    warn() { },
+    error() { },
+};
+//# sourceMappingURL=index.js.map

package/dist/shared/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/shared/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,8BAA8B;AAC9B,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAqCtC,+EAA+E;AAC/E,iCAAiC;AACjC,+EAA+E;AAE/E,uCAAuC;AACvC,MAAM,CAAC,MAAM,WAAW,GAAG;IAC1B,gBAAgB;IAChB,QAAQ;IACR,QAAQ;IACR,cAAc;IACd,OAAO;IACP,aAAa;IACb,YAAY;IACZ,eAAe;IACf,eAAe;IACf,eAAe;IACf,WAAW;CACF,CAAC;AAGX,4DAA4D;AAC5D,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,OAAO,CAAU,CAAC;AAGhD,uDAAuD;AACvD,MAAM,CAAC,MAAM,aAAa,GAAG;IAC5B,OAAO;IACP,QAAQ;IACR,WAAW;IACX,MAAM;IACN,OAAO;IACP,aAAa;IACb,YAAY;CACH,CAAC;AA+LX,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAE/E;;;;;;;;;;;GAWG;AACH,sGAAsG;AACtG,MAAM,uBAAuB,GAAa;IACzC,6CAA6C;IAC7C,iCAAiC;IACjC,kEAAkE;IAClE,oBAAoB;IACpB,yCAAyC;IACzC,uBAAuB;IACvB,sCAAsC;IACtC,qBAAqB;IACrB,gEAAgE;IAChE,gCAAgC;CAChC,CAAC;AACF,oCAAoC;AAEpC,2EAA2E;AAC3E,MAAM,UAAU,mBAAmB,CAAC,OAAe;IAClD,IAAI,MAAM,GAAG,OAAO,CAAC;IACrB,KAAK,MAAM,OAAO,IAAI,uBAAuB,EAAE,CAAC;QAC/C,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC;QACtB,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC;AAaD,uDAAuD;AACvD,MAAM,CAAC,MAAM,YAAY,GAAW;IACnC,GAAG,KAAI,CAAC;IACR,IAAI,KAAI,CAAC;IACT,KAAK,KAAI,CAAC;CACV,CAAC"}

package/package.json

@@ -0,0 +1,108 @@
+{
+  "name": "@myrialabs/ptykit",
+  "version": "0.0.1",
+  "description": "PTY sessions over WebSocket for Node & Bun — collaborative rooms, serialized-scrollback reattach, and a resilient browser client with one typed API.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    },
+    "./svelte": {
+      "types": "./src/client/svelte/index.d.ts",
+      "svelte": "./src/client/svelte/index.js",
+      "default": "./src/client/svelte/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "src/client/svelte",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "bun test",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "bun run clean && bun run build"
+  },
+  "keywords": [
+    "pty",
+    "pseudoterminal",
+    "terminal",
+    "websocket",
+    "xterm",
+    "bun-pty",
+    "node-pty",
+    "scrollback",
+    "reattach",
+    "shell",
+    "collaborative",
+    "browser-terminal",
+    "svelte",
+    "bun",
+    "node",
+    "typescript"
+  ],
+  "author": "Myria Labs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/myrialabs/ptykit.git"
+  },
+  "homepage": "https://github.com/myrialabs/ptykit#readme",
+  "bugs": {
+    "url": "https://github.com/myrialabs/ptykit/issues"
+  },
+  "dependencies": {
+    "@xterm/headless": "^6.0.0",
+    "@xterm/addon-serialize": "^0.14.0"
+  },
+  "optionalDependencies": {
+    "bun-pty": "^0.4.10",
+    "node-pty": "^1.1.0",
+    "ws": "^8.21.0"
+  },
+  "peerDependencies": {
+    "@xterm/xterm": "^6.0.0",
+    "@xterm/addon-fit": "^0.11.0",
+    "svelte": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@xterm/xterm": {
+      "optional": true
+    },
+    "@xterm/addon-fit": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.31.0",
+    "@types/bun": "latest",
+    "@types/node": "^22.10.0",
+    "@types/ws": "^8.18.1",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/xterm": "^6.0.0",
+    "eslint": "^9.31.0",
+    "globals": "^16.3.0",
+    "svelte": "^5.0.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.37.0"
+  }
+}

package/src/client/svelte/PtyTerminal.svelte

@@ -0,0 +1,146 @@
+<!--
+  PtyTerminal — official Svelte component for `ptykit/svelte`.
+
+  A thin reactive shell over `mountTerminal` from `ptykit/client`, which owns all
+  the xterm.js + FitAddon + session wiring. xterm is imported dynamically there,
+  so the component is SSR-safe (it only touches the DOM in the browser).
+
+  Peer deps (provided by the consuming app): svelte, @xterm/xterm, @xterm/addon-fit.
+-->
+<script>
+	import { mountTerminal } from '@myrialabs/ptykit/client';
+
+	let {
+		// --- connection ---
+		sessionId,
+		url,
+		namespace = undefined,
+		create = false,
+		client = undefined,
+		reconnect = undefined,
+		persistence = undefined,
+		requestTimeoutMs = undefined,
+
+		// --- session (used when creating) ---
+		cols = undefined,
+		rows = undefined,
+		cwd = undefined,
+		shell = undefined,
+
+		// --- terminal appearance ---
+		scrollback = 5000,
+		fontSize = 13,
+		fontFamily = 'ui-monospace, SFMono-Regular, Menlo, monospace',
+		lineHeight = 1.0,
+		cursorBlink = true,
+		cursorStyle = 'block',
+		theme = undefined,
+		terminalOptions = {},
+
+		// --- behavior ---
+		fit = true,
+		fitDebounceMs = 100,
+		showStatus = true,
+
+		// --- styling ---
+		class: className = '',
+
+		// --- lifecycle callbacks ---
+		onready = undefined,
+		ondata = undefined,
+		onexit = undefined,
+		onstatus = undefined,
+		onerror = undefined,
+		ondirectory = undefined,
+	} = $props();
+
+	/** @type {'connected' | 'reconnecting' | 'disconnected'} */
+	let status = $state('reconnecting');
+	/** @type {HTMLDivElement | undefined} */
+	let container = $state();
+
+	$effect(() => {
+		if (!container) return;
+		let cancelled = false;
+		/** @type {import('@myrialabs/ptykit/client').TerminalHandle | undefined} */
+		let handle;
+
+		mountTerminal(container, {
+			url,
+			sessionId,
+			namespace,
+			create,
+			client,
+			reconnect,
+			persistence,
+			requestTimeoutMs,
+			cols,
+			rows,
+			cwd,
+			shell,
+			scrollback,
+			fontSize,
+			fontFamily,
+			lineHeight,
+			cursorBlink,
+			cursorStyle,
+			theme,
+			terminalOptions,
+			fit,
+			fitDebounceMs,
+			onData: ondata,
+			onExit: onexit,
+			onError: onerror,
+			onDirectory: ondirectory,
+			onStatus: (s) => {
+				status = s;
+				onstatus?.(s);
+			},
+		})
+			.then((h) => {
+				if (cancelled) {
+					h.dispose();
+					return;
+				}
+				handle = h;
+				onready?.({ client: h.client, session: h.session, terminal: h.terminal });
+			})
+			.catch(() => {
+				/* onError (if provided) was already invoked inside mountTerminal */
+			});
+
+		return () => {
+			cancelled = true;
+			handle?.dispose();
+		};
+	});
+</script>
+
+<div class="ptykit-terminal {className}" data-status={status}>
+	{#if showStatus}
+		<div class="ptykit-terminal__status">{status}</div>
+	{/if}
+	<div class="ptykit-terminal__screen" bind:this={container}></div>
+</div>
+
+<style>
+	.ptykit-terminal {
+		position: relative;
+		width: 100%;
+		height: 100%;
+	}
+	.ptykit-terminal__screen {
+		width: 100%;
+		height: 100%;
+	}
+	.ptykit-terminal__status {
+		position: absolute;
+		top: 4px;
+		right: 8px;
+		z-index: 1;
+		font: 11px/1.4 ui-monospace, monospace;
+		opacity: 0.6;
+		pointer-events: none;
+		text-transform: uppercase;
+	}
+</style>

package/src/client/svelte/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Type declarations for `ptykit/svelte`.
+ *
+ * The component ships as raw `.svelte` source (resolved via the `svelte` export
+ * condition by Svelte-aware bundlers). These hand-written types describe its
+ * public props.
+ */
+
+import type { Component } from 'svelte';
+import type {
+	ClientSession,
+	PtyKitClient,
+	ReconnectOptions,
+	SessionPersistence,
+} from '../index.js';
+
+export interface PtyTerminalReadyContext {
+	client: PtyKitClient;
+	session: ClientSession;
+	/** The xterm `Terminal` instance (typed loosely to avoid a hard xterm dep). */
+	terminal: unknown;
+}
+
+export interface PtyTerminalProps {
+	// connection
+	/** Session to attach to / create (created server-side if new). */
+	sessionId: string;
+	/** WebSocket endpoint, e.g. `/pty`. */
+	url: string;
+	/** Room/namespace. Required when `create` is true. */
+	namespace?: string;
+	/** Create instead of attach. Default `false`. */
+	create?: boolean;
+	/** Reuse an existing client instead of creating one. */
+	client?: PtyKitClient;
+	/** Reconnect tuning for the internally-created client. */
+	reconnect?: ReconnectOptions;
+	/** sessionId persistence override. */
+	persistence?: SessionPersistence;
+	/** RPC timeout (ms). */
+	requestTimeoutMs?: number;
+
+	// session (used when creating)
+	cols?: number;
+	rows?: number;
+	cwd?: string;
+	shell?: string;
+
+	// terminal appearance
+	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>;
+
+	// behavior
+	/** Attach a FitAddon + ResizeObserver. Default `true`. */
+	fit?: boolean;
+	fitDebounceMs?: number;
+	/** Show the built-in connection-status chip. Default `true`. */
+	showStatus?: boolean;
+
+	// styling
+	/** Extra class on the root element. */
+	class?: string;
+
+	// lifecycle callbacks
+	onready?: (ctx: PtyTerminalReadyContext) => void;
+	ondata?: (chunk: string) => void;
+	onexit?: (exitCode: number) => void;
+	onstatus?: (status: 'connected' | 'reconnecting' | 'disconnected') => void;
+	onerror?: (error: unknown) => void;
+	ondirectory?: (directory: string) => void;
+}
+
+/** `<PtyTerminal sessionId url … />` — the official Svelte terminal component. */
+declare const PtyTerminal: Component<PtyTerminalProps>;
+export { PtyTerminal };
+export default PtyTerminal;