@myrialabs/ptykit 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Myria Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,260 @@
+<p align="center">
+  <img src="https://ptykit.myrialabs.dev/favicon.svg" alt="PtyKit" width="72" height="72" />
+</p>
+
+<h1 align="center">PtyKit</h1>
+
+<p align="center">
+  <strong>PTY sessions over WebSocket for Node &amp; Bun.</strong><br />
+  Collaborative rooms, serialized-scrollback reattach, and a resilient browser
+  client — one typed API.
+</p>
+
+<p align="center">
+  <a href="https://ptykit.myrialabs.dev">Website</a> ·
+  <a href="https://www.npmjs.com/package/@myrialabs/ptykit">npm</a> ·
+  <a href="./docs/api.md">API reference</a> ·
+  <a href="./docs/server.md">Server</a> ·
+  <a href="./docs/client.md">Client</a> ·
+  <a href="./examples/README.md">Examples</a> ·
+  <a href="https://github.com/myrialabs/ptykit/issues">Issues</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@myrialabs/ptykit"><img src="https://img.shields.io/npm/v/@myrialabs/ptykit" alt="npm version" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
+  <img src="https://img.shields.io/badge/runtime-Node%2018%2B%20%7C%20Bun-black" alt="Node 18+ and Bun" />
+</p>
+
+---
+
+PtyKit runs interactive shells server-side and streams them to the browser over a
+single WebSocket. Output is kept in a headless terminal so a refresh, a dropped
+connection, or a second viewer all replay the exact screen — no lost bytes, no
+double output. The PTY backend is auto-detected (`bun-pty` on Bun, `node-pty` on
+Node); you bring the auth.
+
+```ts
+// Server
+import { PtyKit, createPtyKitServer } from '@myrialabs/ptykit';
+
+const manager = new PtyKit();
+const server = createPtyKitServer(manager, {
+  path: '/pty',
+  authorize: (ctx) => ctx.conn.data.user?.canAccess(ctx.namespace) ?? false,
+});
+
+Bun.serve({ port: 3000, fetch: server.fetch, websocket: server.websocket });
+```
+
+```ts
+// Browser
+import { PtyKitClient } from '@myrialabs/ptykit/client';
+
+const client = new PtyKitClient({ url: '/pty', namespace: 'project-42' });
+const session = await client.attach('project-42-terminal-1');
+session.onData((chunk) => term.write(chunk));
+term.onData((data) => session.write(data));
+```
+
+## Why PtyKit
+
+- **WebSocket only** — one multiplexed control + data channel. No SSE, no
+  transport option, no polling.
+- **Collaborative rooms** — output broadcasts to a room (default = namespace), so
+  **N clients ↔ 1 session**. Multiple viewers see the same live terminal.
+- **Reattach that just works** — scrollback lives server-side in a headless
+  xterm and replays as a single serialized frame. Survives refresh, disconnect,
+  and tab switches with **zero data loss** and no double output.
+- **Auto-detected backend** — `bun-pty` on Bun (the tested path), `node-pty` on
+  Node (experimental). A Node consumer never builds bun-pty's rust/ffi, and
+  vice-versa — both are optional, lazily loaded.
+- **Resilient client** — reconnect with exponential backoff, heal-reconnect for
+  "open but dead" sockets, and idempotency-aware resend, all on by default.
+- **Bring your own auth** — an `authorize` hook enforces namespace access with
+  anti-hijack ownership checks. The library ships no auth of its own.
+- **Quiet, typed core** — no stdout/stderr writes, `sideEffects: false`, JSDoc on
+  every export, runs on Node 18+ and Bun.
+
+## Install
+
+```sh
+bun add @myrialabs/ptykit          # or: npm i @myrialabs/ptykit / pnpm add @myrialabs/ptykit
+```
+
+The PTY backend is an **optional** dependency resolved at runtime: `bun-pty` on
+Bun, `node-pty` on Node. For the Node WebSocket server, `ws` is used (also
+optional). Browser peers (`@xterm/xterm`, `@xterm/addon-fit`) and `svelte` are
+optional peer dependencies you already have in a frontend.
+
+## Entry points
+
+| Import | What |
+| --- | --- |
+| `@myrialabs/ptykit` | Core session engine (`PtyKit`) + WebSocket server (`createPtyKitServer`). |
+| `@myrialabs/ptykit/client` | Framework-agnostic browser client (`mountTerminal`, `PtyKitClient`, `attachFit`). |
+| `@myrialabs/ptykit/svelte` | Official Svelte component (`<PtyTerminal/>`). |
+
+## Quick start
+
+| Task | API |
+| --- | --- |
+| Create the manager | `const m = new PtyKit({ scrollback: 5000 })` |
+| Mount on Bun | `Bun.serve({ fetch: server.fetch, websocket: server.websocket })` |
+| Mount on Node | `await server.attach(httpServer)` |
+| Terminal (vanilla) | `await mountTerminal(el, { url: '/pty', namespace, sessionId, create: true })` |
+| Attach (client) | `await client.attach(sessionId)` |
+| Create (client) | `await client.create({ cols, rows })` |
+| Stream output | `session.onData((chunk) => term.write(chunk))` |
+| Send keystrokes | `session.write(data)` |
+| Resize | `attachFit(session, term, fitAddon)` |
+| Svelte | `<PtyTerminal {sessionId} url="/pty" namespace="project-42" />` |
+
+## Server
+
+`createPtyKitServer` mounts onto the HTTP server you already have.
+
+**Bun** — wire `fetch` + `websocket` into `Bun.serve`:
+
+```ts
+Bun.serve({ port: 3000, fetch: server.fetch, websocket: server.websocket });
+```
+
+**Node** — attach to an `http.Server` (uses the optional `ws` package):
+
+```ts
+import http from 'node:http';
+const httpServer = http.createServer(app);
+await server.attach(httpServer);
+httpServer.listen(3000);
+```
+
+The `PtyKit` manager owns the sessions and is transport-agnostic:
+
+```ts
+const manager = new PtyKit({
+  scrollback: 5000,         // headless xterm lines
+  idleTtl: null,            // sessions live until killed; a number opts into idle reaping
+  retainExitedMs: 5 * 60_000, // keep exited sessions this long for reconnect replay
+  env: { sanitize: true, inject: { MY_VAR: '1' } }, // strip runtime pollution, inject yours
+});
+```
+
+See [docs/server.md](./docs/server.md) for the full surface, operations, and events.
+
+## Collaborative rooms
+
+Output broadcasts to a room (default = the namespace) and clients filter by
+`sessionId`, so any number of clients can attach to the same session and watch
+the same live terminal. The serialized reattach frame is unicast to the joining
+client, so existing viewers are never repainted.
+
+```ts
+const server = createPtyKitServer(manager, {
+  room: (ctx) => ctx.namespace, // or group however you like
+});
+```
+
+## The resilient client
+
+Skip the xterm boilerplate with `mountTerminal` — the framework-agnostic
+counterpart to `<PtyTerminal/>`. Give it a container and a url; it creates the
+terminal, fits it, opens the session, and wires output⇄input, while staying fully
+configurable.
+
+```ts
+import { mountTerminal } from '@myrialabs/ptykit/client';
+
+const { session, terminal, dispose } = await mountTerminal(el, {
+  url: '/pty',
+  namespace: 'project-42',
+  sessionId: 'project-42-terminal-1',
+  create: true,
+  onStatus: (s) => render(s),
+});
+```
+
+Need full control? Drop down to `PtyKitClient`. Reconnect is on by default —
+exponential backoff (1s → 30s), heal-reconnect for sockets that are "open but
+dead", and idempotency-aware resend. On reconnect, every known session is
+re-attached so the room subscription and scrollback recover.
+
+```ts
+const client = new PtyKitClient({
+  url: '/pty',
+  namespace: 'project-42',
+  reconnect: { enabled: true, baseDelayMs: 1000, maxDelayMs: 30_000, maxAttempts: 5 },
+  persistence: { load, save }, // optional: own the active-session id yourself
+});
+
+client.onStatus((s) => render(s)); // 'connected' | 'reconnecting' | 'disconnected'
+```
+
+See [docs/client.md](./docs/client.md) for `mountTerminal`, `attachFit`,
+persistence, and the session API.
+
+## Svelte
+
+```svelte
+<script>
+  import { PtyTerminal } from '@myrialabs/ptykit/svelte';
+</script>
+
+<PtyTerminal sessionId="project-42-terminal-1" url="/pty" namespace="project-42" />
+```
+
+The component is fully configurable (theme, font, reconnect, lifecycle
+callbacks, …). See [docs/svelte.md](./docs/svelte.md).
+
+## Security
+
+The `authorize` hook **defaults to allow-all** so the package is friendly to try
+locally — this is unsafe in production. A network-reachable deployment must
+provide an `authorize` implementation that checks the connection's identity
+(populated by `onUpgrade`) against the requested `namespace`. PtyKit also rejects
+cross-namespace `sessionId` access (anti-hijack), but it cannot know who your
+users are — that's your hook's job.
+
+## node-pty status
+
+`bun-pty` is the default, tested backend. The `node-pty` adapter exists and
+auto-activates under Node, but is marked **experimental** until the scale and
+auto-detect benchmarks gate it. On the benchmark machine (Node 25, macOS arm64),
+node-pty failed to spawn (`posix_spawnp`, reproduced with raw node-pty) — see
+[bench-results.md](./bench-results.md).
+
+## Performance
+
+Measured on a dev laptop (Apple M2, Bun 1.3.14). Reproduce with `bun bench.ts`;
+full numbers in [bench-results.md](./bench-results.md).
+
+- **Throughput overhead** of the wrapped pipeline vs raw bun-pty: **~7%**
+  (target <10%) — the cost of persist-to-headless-first + batching.
+- **Reattach** serialize latency: p50 ~3–9ms, p95 ~10–19ms across 10KB/100KB/1MB
+  buffers; the newest output is always present.
+- **Idle footprint**: ~0.13 MB of parent-process RSS per session. In-memory
+  scrollback was fine at 100 sessions — no disk spill needed.
+
+## Documentation
+
+- [API reference](./docs/api.md) — every export across the three entry points.
+- [Server](./docs/server.md) — `PtyKit`, `createPtyKitServer`, rooms, `authorize`.
+- [Client](./docs/client.md) — `mountTerminal`, `PtyKitClient`, reconnect, persistence, `attachFit`.
+- [Svelte](./docs/svelte.md) — the `<PtyTerminal/>` component.
+- [Examples](./examples/README.md) — runnable scenarios.
+
+## Support
+
+If PtyKit is useful to you, consider supporting its development:
+
+| Method | Address / Link |
+|--------|----------------|
+| Bitcoin (BTC) | `bc1qd9fyx4r84cce2a9hkjksetah802knadw5msls3` |
+| Solana (SOL) | `Ev3P4KLF1PNC5C9rZYP8M3DdssyBQAQAiNJkvNmPQPVs` |
+| Ethereum (ERC-20) | `0x61D826e5b666AA5345302EEEd485Acca39b1AFCF` |
+| USDT (TRC-20) | `TLH49i3EoVKhFyLb6u2JUXZWScK7uzksdC` |
+| Saweria | [saweria.co/myrialabs](https://saweria.co/myrialabs) |
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/client/fit.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `attachFit` (R15) — bind an xterm `FitAddon` + `ResizeObserver` to a session.
+ *
+ * Fits the terminal to its container on resize (debounced, default 100ms),
+ * skips redundant resizes, and forwards the new dimensions to the server.
+ */
+import type { ClientSession } from './pty-kit-client.js';
+/** Minimal xterm Terminal shape we depend on. */
+interface TerminalLike {
+    element?: HTMLElement | undefined;
+}
+/** Minimal FitAddon shape we depend on. */
+interface FitAddonLike {
+    fit(): void;
+    proposeDimensions(): {
+        cols: number;
+        rows: number;
+    } | undefined;
+}
+export interface AttachFitOptions {
+    debounceMs?: number;
+}
+/**
+ * Observe the terminal's container, fit on resize, and send `resize` to the
+ * server. Returns a disposer that stops observing.
+ */
+export declare function attachFit(session: Pick<ClientSession, 'resize'>, term: TerminalLike, fitAddon: FitAddonLike, options?: AttachFitOptions): () => void;
+export {};
+//# sourceMappingURL=fit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fit.d.ts","sourceRoot":"","sources":["../../src/client/fit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,iDAAiD;AACjD,UAAU,YAAY;IACrB,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAClC;AACD,2CAA2C;AAC3C,UAAU,YAAY;IACrB,GAAG,IAAI,IAAI,CAAC;IACZ,iBAAiB,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;CAChE;AAED,MAAM,WAAW,gBAAgB;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACxB,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,EACtC,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,YAAY,EACtB,OAAO,GAAE,gBAAqB,GAC5B,MAAM,IAAI,CAiCZ"}

package/dist/client/fit.js

@@ -0,0 +1,45 @@
+/**
+ * `attachFit` (R15) — bind an xterm `FitAddon` + `ResizeObserver` to a session.
+ *
+ * Fits the terminal to its container on resize (debounced, default 100ms),
+ * skips redundant resizes, and forwards the new dimensions to the server.
+ */
+/**
+ * Observe the terminal's container, fit on resize, and send `resize` to the
+ * server. Returns a disposer that stops observing.
+ */
+export function attachFit(session, term, fitAddon, options = {}) {
+    const debounceMs = options.debounceMs ?? 100;
+    let timer = null;
+    let last = null;
+    const run = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            try {
+                fitAddon.fit();
+                const dims = fitAddon.proposeDimensions();
+                if (!dims)
+                    return;
+                if (last && last.cols === dims.cols && last.rows === dims.rows)
+                    return;
+                last = { cols: dims.cols, rows: dims.rows };
+                void session.resize(dims.cols, dims.rows);
+            }
+            catch {
+                /* container may have zero dimensions; will retry on next resize */
+            }
+        }, debounceMs);
+    };
+    const target = term.element?.parentElement ?? term.element ?? null;
+    const observer = typeof ResizeObserver !== 'undefined' && target ? new ResizeObserver(run) : null;
+    observer?.observe(target);
+    // Initial fit.
+    run();
+    return () => {
+        if (timer)
+            clearTimeout(timer);
+        observer?.disconnect();
+    };
+}
+//# sourceMappingURL=fit.js.map

package/dist/client/fit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fit.js","sourceRoot":"","sources":["../../src/client/fit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkBH;;;GAGG;AACH,MAAM,UAAU,SAAS,CACxB,OAAsC,EACtC,IAAkB,EAClB,QAAsB,EACtB,UAA4B,EAAE;IAE9B,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,GAAG,CAAC;IAC7C,IAAI,KAAK,GAAyC,IAAI,CAAC;IACvD,IAAI,IAAI,GAA0C,IAAI,CAAC;IAEvD,MAAM,GAAG,GAAG,GAAG,EAAE;QAChB,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QAC/B,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YACvB,IAAI,CAAC;gBACJ,QAAQ,CAAC,GAAG,EAAE,CAAC;gBACf,MAAM,IAAI,GAAG,QAAQ,CAAC,iBAAiB,EAAE,CAAC;gBAC1C,IAAI,CAAC,IAAI;oBAAE,OAAO;gBAClB,IAAI,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI;oBAAE,OAAO;gBACvE,IAAI,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;gBAC5C,KAAK,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3C,CAAC;YAAC,MAAM,CAAC;gBACR,mEAAmE;YACpE,CAAC;QACF,CAAC,EAAE,UAAU,CAAC,CAAC;IAChB,CAAC,CAAC;IAEF,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,aAAa,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC;IACnE,MAAM,QAAQ,GACb,OAAO,cAAc,KAAK,WAAW,IAAI,MAAM,CAAC,CAAC,CAAC,IAAI,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAClF,QAAQ,EAAE,OAAO,CAAC,MAAiB,CAAC,CAAC;IAErC,eAAe;IACf,GAAG,EAAE,CAAC;IAEN,OAAO,GAAG,EAAE;QACX,IAAI,KAAK;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QAC/B,QAAQ,EAAE,UAAU,EAAE,CAAC;IACxB,CAAC,CAAC;AACH,CAAC"}

package/dist/client/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `ptykit/client` — framework-agnostic browser client.
+ */
+export { PtyKitClient, ClientSession, type PtyKitClientOptions, type OpenOptions, } from './pty-kit-client.js';
+export { attachFit, type AttachFitOptions } from './fit.js';
+export { mountTerminal, type MountTerminalOptions, type TerminalHandle, } from './terminal.js';
+export { defaultPersistence, type SessionPersistence } from './persistence.js';
+export { WsCore, type WsCoreOptions, type WSStatus, type ReconnectOptions, type WebSocketFactory, type WebSocketLike, } from './ws-core.js';
+export type { Seq, OutputEvent, ReadyEvent, ExitEvent, CreateSessionResponse, } from '../shared/index.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACN,YAAY,EACZ,aAAa,EACb,KAAK,mBAAmB,EACxB,KAAK,WAAW,GAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,EACN,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,cAAc,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,EACN,MAAM,EACN,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GAClB,MAAM,cAAc,CAAC;AAGtB,YAAY,EACX,GAAG,EACH,WAAW,EACX,UAAU,EACV,SAAS,EACT,qBAAqB,GACrB,MAAM,oBAAoB,CAAC"}

package/dist/client/index.js

@@ -0,0 +1,9 @@
+/**
+ * `ptykit/client` — framework-agnostic browser client.
+ */
+export { PtyKitClient, ClientSession, } from './pty-kit-client.js';
+export { attachFit } from './fit.js';
+export { mountTerminal, } from './terminal.js';
+export { defaultPersistence } from './persistence.js';
+export { WsCore, } from './ws-core.js';
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACN,YAAY,EACZ,aAAa,GAGb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAyB,MAAM,UAAU,CAAC;AAC5D,OAAO,EACN,aAAa,GAGb,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,kBAAkB,EAA2B,MAAM,kBAAkB,CAAC;AAC/E,OAAO,EACN,MAAM,GAMN,MAAM,cAAc,CAAC"}

package/dist/client/persistence.d.ts

@@ -0,0 +1,15 @@
+/**
+ * sessionId persistence (R13, Recommendation 2).
+ *
+ * Default: the active session id is stored in `sessionStorage`, scoped per
+ * namespace, with an in-memory fallback when storage is unavailable (SSR / Node).
+ * Callers that own the authoritative tab list (e.g. a server DB) override via the
+ * `persistence` hook.
+ */
+export interface SessionPersistence {
+    load(namespace: string): string | null;
+    save(namespace: string, sessionId: string): void;
+}
+/** The default sessionStorage-backed persistence (with in-memory fallback). */
+export declare function defaultPersistence(): SessionPersistence;
+//# sourceMappingURL=persistence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../src/client/persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,kBAAkB;IAClC,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACvC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACjD;AAID,+EAA+E;AAC/E,wBAAgB,kBAAkB,IAAI,kBAAkB,CAiCvD"}

package/dist/client/persistence.js

@@ -0,0 +1,47 @@
+/**
+ * sessionId persistence (R13, Recommendation 2).
+ *
+ * Default: the active session id is stored in `sessionStorage`, scoped per
+ * namespace, with an in-memory fallback when storage is unavailable (SSR / Node).
+ * Callers that own the authoritative tab list (e.g. a server DB) override via the
+ * `persistence` hook.
+ */
+const storageKey = (namespace) => `ptykit-active-session-${namespace}`;
+/** The default sessionStorage-backed persistence (with in-memory fallback). */
+export function defaultPersistence() {
+    const hasStorage = (() => {
+        try {
+            return typeof sessionStorage !== 'undefined' && sessionStorage !== null;
+        }
+        catch {
+            return false;
+        }
+    })();
+    const memory = new Map();
+    return {
+        load(namespace) {
+            if (hasStorage) {
+                try {
+                    return sessionStorage.getItem(storageKey(namespace));
+                }
+                catch {
+                    return null;
+                }
+            }
+            return memory.get(namespace) ?? null;
+        },
+        save(namespace, sessionId) {
+            if (hasStorage) {
+                try {
+                    sessionStorage.setItem(storageKey(namespace), sessionId);
+                    return;
+                }
+                catch {
+                    /* fall through to memory */
+                }
+            }
+            memory.set(namespace, sessionId);
+        },
+    };
+}
+//# sourceMappingURL=persistence.js.map

package/dist/client/persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../../src/client/persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,MAAM,UAAU,GAAG,CAAC,SAAiB,EAAE,EAAE,CAAC,yBAAyB,SAAS,EAAE,CAAC;AAE/E,+EAA+E;AAC/E,MAAM,UAAU,kBAAkB;IACjC,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE;QACxB,IAAI,CAAC;YACJ,OAAO,OAAO,cAAc,KAAK,WAAW,IAAI,cAAc,KAAK,IAAI,CAAC;QACzE,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,KAAK,CAAC;QACd,CAAC;IACF,CAAC,CAAC,EAAE,CAAC;IACL,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEzC,OAAO;QACN,IAAI,CAAC,SAAS;YACb,IAAI,UAAU,EAAE,CAAC;gBAChB,IAAI,CAAC;oBACJ,OAAO,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;gBACtD,CAAC;gBAAC,MAAM,CAAC;oBACR,OAAO,IAAI,CAAC;gBACb,CAAC;YACF,CAAC;YACD,OAAO,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC;QACtC,CAAC;QACD,IAAI,CAAC,SAAS,EAAE,SAAS;YACxB,IAAI,UAAU,EAAE,CAAC;gBAChB,IAAI,CAAC;oBACJ,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC;oBACzD,OAAO;gBACR,CAAC;gBAAC,MAAM,CAAC;oBACR,4BAA4B;gBAC7B,CAAC;YACF,CAAC;YACD,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QAClC,CAAC;KACD,CAAC;AACH,CAAC"}

package/dist/client/pty-kit-client.d.ts

@@ -0,0 +1,122 @@
+/**
+ * `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 { type Seq } from '../shared/index.js';
+import { type ReconnectOptions, type WSStatus, type WebSocketFactory } from './ws-core.js';
+import { type SessionPersistence } from './persistence.js';
+export interface PtyKitClientOptions {
+    url: string;
+    /** Default namespace for `create`/`attach` when not passed explicitly. */
+    namespace?: string;
+    reconnect?: ReconnectOptions;
+    persistence?: SessionPersistence;
+    /** Injectable WebSocket constructor (defaults to global `WebSocket`). */
+    WebSocketImpl?: WebSocketFactory;
+    requestTimeoutMs?: number;
+}
+export interface OpenOptions {
+    sessionId?: string;
+    namespace?: string;
+    cwd?: string;
+    cols?: number;
+    rows?: number;
+    shell?: string;
+}
+interface CreateRequest {
+    sessionId: string;
+    namespace: string;
+    cwd?: string;
+    cols?: number;
+    rows?: number;
+    shell?: string;
+}
+type DataCb = (chunk: string) => void;
+type ExitCb = (exitCode: number) => void;
+type DirCb = (directory: string) => void;
+type ErrCb = (error: string) => void;
+/** A handle to one PTY session over the shared socket. */
+export declare class ClientSession {
+    private readonly client;
+    readonly sessionId: string;
+    readonly namespace: string;
+    /** @internal — the request used to (re)attach on reconnect. */
+    readonly createRequest: CreateRequest;
+    private lastSeq;
+    /** Output that arrived before the first `onData` listener (e.g. reattach replay). */
+    private pending;
+    private pendingBytes;
+    private static readonly PENDING_CAP;
+    private readonly dataCbs;
+    private readonly exitCbs;
+    private readonly dirCbs;
+    private readonly errCbs;
+    constructor(client: PtyKitClient, request: CreateRequest);
+    /** Subscribe to terminal output (deduped by seq; replay frames stripped). */
+    onData(cb: DataCb): () => void;
+    onExit(cb: ExitCb): () => void;
+    onDirectory(cb: DirCb): () => void;
+    onError(cb: ErrCb): () => void;
+    /** @internal Route an output event for this session. */
+    _handleOutput(content: string, seq?: Seq): void;
+    /** @internal */
+    _handleExit(exitCode: number): void;
+    /** @internal */
+    _handleDirectory(directory: string): void;
+    /** @internal */
+    _handleError(error: string): void;
+    /** Send raw keystrokes (fire-and-forget pass-through, R16). */
+    write(data: string): void;
+    resize(cols: number, rows: number): Promise<void>;
+    cancel(): Promise<void>;
+    clear(): Promise<void>;
+    /** Kill the session on the server. */
+    kill(): Promise<void>;
+    /** Stop receiving locally; does NOT kill the server-side session. */
+    detach(): void;
+}
+export declare class PtyKitClient {
+    private readonly core;
+    private readonly persistence;
+    private readonly defaultNamespace?;
+    private readonly sessions;
+    private status;
+    private readonly statusCbs;
+    constructor(options: PtyKitClientOptions);
+    /** Subscribe to connection status. Fires immediately with the current value. */
+    onStatus(cb: (status: WSStatus) => void): () => void;
+    connected(): boolean;
+    private resolveNamespace;
+    private generateId;
+    /** Create a new session (or attach if the id already exists — server is idempotent). */
+    create(options?: OpenOptions): Promise<ClientSession>;
+    /** Attach to an existing session (replays serialized scrollback). */
+    attach(sessionId?: string, options?: OpenOptions): Promise<ClientSession>;
+    private open;
+    private reattachAll;
+    /** List sessions a namespace currently has on the server. */
+    listSessions(namespace?: string): Promise<any>;
+    disconnect(): void;
+    /** @internal */
+    _emitInput(sessionId: string, data: string): void;
+    /** @internal */
+    _resize(sessionId: string, cols: number, rows: number): Promise<void>;
+    /** @internal */
+    _cancel(sessionId: string): Promise<void>;
+    /** @internal */
+    _clear(sessionId: string): Promise<void>;
+    /** @internal */
+    _kill(sessionId: string): Promise<void>;
+    /** @internal */
+    _forget(sessionId: string): void;
+}
+export {};
+//# sourceMappingURL=pty-kit-client.d.ts.map

package/dist/client/pty-kit-client.d.ts.map

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