@slopus/ghostty-web 0.1.0

package/dist/WirePacket.d.ts

@@ -0,0 +1,29 @@
+export declare const WIRE_VERSION = 1;
+export declare const WIRE_HEADER_BYTES = 20;
+export declare const WIRE_MAGIC = 21076;
+export declare const enum WirePacketType {
+    ClientHello = 1,
+    Welcome = 2,
+    Output = 3,
+    OutputAck = 4,
+    Input = 5,
+    InputAck = 6,
+    Resize = 7,
+    ResizeAck = 8,
+    GridKeyframe = 9,
+    GridPatch = 10,
+    GridAck = 11,
+    Mode = 12,
+    Resync = 13,
+    ScrollbackRequest = 14,
+    ScrollbackPage = 15,
+    Exit = 16,
+    Error = 17,
+    ResizeApplied = 18
+}
+export interface WirePacket {
+    payload: Uint8Array;
+    sequence: number;
+    type: WirePacketType;
+}
+//# sourceMappingURL=WirePacket.d.ts.map

package/dist/WirePacket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WirePacket.d.ts","sourceRoot":"","sources":["../sources/WirePacket.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY,IAAI,CAAC;AAC9B,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,eAAO,MAAM,UAAU,QAAS,CAAC;AAEjC,0BAAkB,cAAc;IAC5B,WAAW,IAAI;IACf,OAAO,IAAI;IACX,MAAM,IAAI;IACV,SAAS,IAAI;IACb,KAAK,IAAI;IACT,QAAQ,IAAI;IACZ,MAAM,IAAI;IACV,SAAS,IAAI;IACb,YAAY,IAAI;IAChB,SAAS,KAAK;IACd,OAAO,KAAK;IACZ,IAAI,KAAK;IACT,MAAM,KAAK;IACX,iBAAiB,KAAK;IACtB,cAAc,KAAK;IACnB,IAAI,KAAK;IACT,KAAK,KAAK;IACV,aAAa,KAAK;CACrB;AAED,MAAM,WAAW,UAAU;IACvB,OAAO,EAAE,UAAU,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,cAAc,CAAC;CACxB"}

package/dist/WirePacket.js

@@ -0,0 +1,24 @@
+export const WIRE_VERSION = 1;
+export const WIRE_HEADER_BYTES = 20;
+export const WIRE_MAGIC = 0x5254;
+export var WirePacketType;
+(function (WirePacketType) {
+    WirePacketType[WirePacketType["ClientHello"] = 1] = "ClientHello";
+    WirePacketType[WirePacketType["Welcome"] = 2] = "Welcome";
+    WirePacketType[WirePacketType["Output"] = 3] = "Output";
+    WirePacketType[WirePacketType["OutputAck"] = 4] = "OutputAck";
+    WirePacketType[WirePacketType["Input"] = 5] = "Input";
+    WirePacketType[WirePacketType["InputAck"] = 6] = "InputAck";
+    WirePacketType[WirePacketType["Resize"] = 7] = "Resize";
+    WirePacketType[WirePacketType["ResizeAck"] = 8] = "ResizeAck";
+    WirePacketType[WirePacketType["GridKeyframe"] = 9] = "GridKeyframe";
+    WirePacketType[WirePacketType["GridPatch"] = 10] = "GridPatch";
+    WirePacketType[WirePacketType["GridAck"] = 11] = "GridAck";
+    WirePacketType[WirePacketType["Mode"] = 12] = "Mode";
+    WirePacketType[WirePacketType["Resync"] = 13] = "Resync";
+    WirePacketType[WirePacketType["ScrollbackRequest"] = 14] = "ScrollbackRequest";
+    WirePacketType[WirePacketType["ScrollbackPage"] = 15] = "ScrollbackPage";
+    WirePacketType[WirePacketType["Exit"] = 16] = "Exit";
+    WirePacketType[WirePacketType["Error"] = 17] = "Error";
+    WirePacketType[WirePacketType["ResizeApplied"] = 18] = "ResizeApplied";
+})(WirePacketType || (WirePacketType = {}));

package/dist/WirePacketDecoder.d.ts

@@ -0,0 +1,8 @@
+import { type WirePacket } from "./WirePacket.js";
+/** Incremental bounded decoder. It never recopies the unconsumed byte stream. */
+export declare class WirePacketDecoder {
+    #private;
+    constructor(maxFrameBytes?: number, maxPacketsPerPush?: number);
+    push(data: Uint8Array): readonly WirePacket[];
+}
+//# sourceMappingURL=WirePacketDecoder.d.ts.map

package/dist/WirePacketDecoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WirePacketDecoder.d.ts","sourceRoot":"","sources":["../sources/WirePacketDecoder.ts"],"names":[],"mappings":"AAEA,OAAO,EAIH,KAAK,UAAU,EAElB,MAAM,iBAAiB,CAAC;AAKzB,iFAAiF;AACjF,qBAAa,iBAAiB;;gBAMd,aAAa,SAAmB,EAAE,iBAAiB,SAAQ;IAmBvE,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,UAAU,EAAE;CAoGhD"}

package/dist/WirePacketDecoder.js

@@ -0,0 +1,130 @@
+import { inflateRawSync } from "node:zlib";
+import { WIRE_HEADER_BYTES, WIRE_MAGIC, WIRE_VERSION, WirePacketType, } from "./WirePacket.js";
+const COMPRESSED = 1;
+const KNOWN_FLAGS = COMPRESSED;
+/** Incremental bounded decoder. It never recopies the unconsumed byte stream. */
+export class WirePacketDecoder {
+    #bufferedBytes = 0;
+    #chunks = [];
+    #maxFrameBytes;
+    #maxPacketsPerPush;
+    constructor(maxFrameBytes = 32 * 1024 * 1024, maxPacketsPerPush = 4_096) {
+        if (!Number.isSafeInteger(maxFrameBytes) ||
+            maxFrameBytes < 1 ||
+            maxFrameBytes > 64 * 1024 * 1024) {
+            throw new Error("Invalid maximum remote terminal frame size.");
+        }
+        if (!Number.isSafeInteger(maxPacketsPerPush) ||
+            maxPacketsPerPush < 1 ||
+            maxPacketsPerPush > 65_536) {
+            throw new Error("Invalid remote terminal packet batch limit.");
+        }
+        this.#maxFrameBytes = maxFrameBytes;
+        this.#maxPacketsPerPush = maxPacketsPerPush;
+    }
+    push(data) {
+        if (data.length > 0) {
+            this.#chunks.push(Buffer.from(data));
+            this.#bufferedBytes += data.length;
+        }
+        if (this.#bufferedBytes > this.#maxFrameBytes + WIRE_HEADER_BYTES) {
+            throw new Error("Remote terminal receive buffer is too large.");
+        }
+        const packets = [];
+        while (this.#bufferedBytes >= WIRE_HEADER_BYTES) {
+            if (packets.length >= this.#maxPacketsPerPush) {
+                throw new Error("Too many remote terminal packets in one read.");
+            }
+            const header = this.#peek(WIRE_HEADER_BYTES);
+            if (header.readUInt16BE(0) !== WIRE_MAGIC)
+                throw new Error("Invalid wire magic.");
+            if (header.readUInt8(2) !== WIRE_VERSION) {
+                throw new Error("Unsupported remote terminal wire version.");
+            }
+            const type = header.readUInt8(3);
+            if (type < WirePacketType.ClientHello || type > WirePacketType.ResizeApplied) {
+                throw new Error("Unknown remote terminal packet type.");
+            }
+            const flags = header.readUInt8(4);
+            if ((flags & ~KNOWN_FLAGS) !== 0)
+                throw new Error("Unknown remote terminal packet flags.");
+            if (header.readUIntBE(5, 3) !== 0)
+                throw new Error("Nonzero reserved wire header bytes.");
+            const length = header.readUInt32BE(16);
+            if (length > this.#maxFrameBytes)
+                throw new Error("Remote terminal frame is too large.");
+            const frameLength = WIRE_HEADER_BYTES + length;
+            if (this.#bufferedBytes < frameLength)
+                break;
+            this.#consume(WIRE_HEADER_BYTES);
+            const encoded = this.#read(length);
+            let payload;
+            try {
+                payload =
+                    flags & COMPRESSED
+                        ? inflateRawSync(encoded, { maxOutputLength: this.#maxFrameBytes })
+                        : encoded;
+            }
+            catch (error) {
+                throw new Error("Invalid compressed remote terminal frame.", { cause: error });
+            }
+            if (payload.length > this.#maxFrameBytes) {
+                throw new Error("Inflated remote terminal frame is too large.");
+            }
+            const sequence = Number(header.readBigUInt64BE(8));
+            if (!Number.isSafeInteger(sequence))
+                throw new Error("Wire sequence is too large.");
+            packets.push({ payload, sequence, type: type });
+        }
+        return packets;
+    }
+    #consume(length) {
+        let remaining = length;
+        while (remaining > 0) {
+            const first = this.#chunks[0];
+            if (first.length <= remaining) {
+                this.#chunks.shift();
+                remaining -= first.length;
+            }
+            else {
+                this.#chunks[0] = first.subarray(remaining);
+                remaining = 0;
+            }
+        }
+        this.#bufferedBytes -= length;
+    }
+    #peek(length) {
+        const first = this.#chunks[0];
+        if (first.length >= length)
+            return first.subarray(0, length);
+        const result = Buffer.allocUnsafe(length);
+        let offset = 0;
+        for (const chunk of this.#chunks) {
+            const copied = Math.min(chunk.length, length - offset);
+            chunk.copy(result, offset, 0, copied);
+            offset += copied;
+            if (offset === length)
+                break;
+        }
+        return result;
+    }
+    #read(length) {
+        if (length === 0)
+            return Buffer.alloc(0);
+        const first = this.#chunks[0];
+        if (first.length === length) {
+            this.#chunks.shift();
+            this.#bufferedBytes -= length;
+            return first;
+        }
+        if (first.length > length) {
+            const result = first.subarray(0, length);
+            this.#chunks[0] = first.subarray(length);
+            this.#bufferedBytes -= length;
+            return result;
+        }
+        const result = this.#peek(length);
+        this.#consume(length);
+        return result;
+    }
+}

package/dist/applyGridPatch.d.ts

@@ -0,0 +1,3 @@
+import type { RemoteTerminalGridPatch, RemoteTerminalGridState } from "./types.js";
+export declare function applyGridPatch(state: RemoteTerminalGridState, patch: RemoteTerminalGridPatch): RemoteTerminalGridState;
+//# sourceMappingURL=applyGridPatch.d.ts.map

package/dist/applyGridPatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyGridPatch.d.ts","sourceRoot":"","sources":["../sources/applyGridPatch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAEnF,wBAAgB,cAAc,CAC1B,KAAK,EAAE,uBAAuB,EAC9B,KAAK,EAAE,uBAAuB,GAC/B,uBAAuB,CAiBzB"}

package/dist/applyGridPatch.js

@@ -0,0 +1,19 @@
+export function applyGridPatch(state, patch) {
+    if (state.revision !== patch.baseRevision)
+        throw new Error("Grid patch base revision mismatch.");
+    const rows = [...state.rows];
+    for (const [index, row] of patch.rows)
+        rows[index] = row;
+    return {
+        cols: patch.cols,
+        coversOutputOffset: patch.coversOutputOffset,
+        cursor: patch.cursor,
+        palette: patch.palette,
+        revision: patch.revision,
+        rows,
+        startRow: patch.startRow,
+        styles: patch.styles,
+        title: patch.title,
+        totalRows: patch.totalRows,
+    };
+}

package/dist/diffGridState.d.ts

@@ -0,0 +1,3 @@
+import type { RemoteTerminalGridPatch, RemoteTerminalGridState } from "./types.js";
+export declare function diffGridState(previous: RemoteTerminalGridState, next: RemoteTerminalGridState): RemoteTerminalGridPatch | undefined;
+//# sourceMappingURL=diffGridState.d.ts.map

package/dist/diffGridState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diffGridState.d.ts","sourceRoot":"","sources":["../sources/diffGridState.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAEnF,wBAAgB,aAAa,CACzB,QAAQ,EAAE,uBAAuB,EACjC,IAAI,EAAE,uBAAuB,GAC9B,uBAAuB,GAAG,SAAS,CA2BrC"}

package/dist/diffGridState.js

@@ -0,0 +1,26 @@
+export function diffGridState(previous, next) {
+    if (previous.cols !== next.cols ||
+        previous.rows.length !== next.rows.length ||
+        previous.startRow !== next.startRow) {
+        return undefined;
+    }
+    const rows = [];
+    for (let index = 0; index < next.rows.length; index += 1) {
+        if (JSON.stringify(previous.rows[index]) !== JSON.stringify(next.rows[index])) {
+            rows.push([index, next.rows[index]]);
+        }
+    }
+    return {
+        baseRevision: previous.revision,
+        cols: next.cols,
+        coversOutputOffset: next.coversOutputOffset,
+        cursor: next.cursor,
+        palette: next.palette,
+        revision: next.revision,
+        rows,
+        startRow: next.startRow,
+        styles: next.styles,
+        title: next.title,
+        totalRows: next.totalRows,
+    };
+}

package/dist/encodeWirePacket.d.ts

@@ -0,0 +1,7 @@
+import { type WirePacket } from "./WirePacket.js";
+export declare function encodeWirePacket(packet: WirePacket): {
+    compressed: boolean;
+    data: Buffer;
+    payloadBytes: number;
+};
+//# sourceMappingURL=encodeWirePacket.d.ts.map

package/dist/encodeWirePacket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encodeWirePacket.d.ts","sourceRoot":"","sources":["../sources/encodeWirePacket.ts"],"names":[],"mappings":"AAEA,OAAO,EAA+C,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAI/F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG;IAClD,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACxB,CAqBA"}

package/dist/encodeWirePacket.js

@@ -0,0 +1,25 @@
+import { deflateRawSync } from "node:zlib";
+import { WIRE_HEADER_BYTES, WIRE_MAGIC, WIRE_VERSION } from "./WirePacket.js";
+const COMPRESSED = 1;
+export function encodeWirePacket(packet) {
+    if (!Number.isSafeInteger(packet.sequence) || packet.sequence < 0) {
+        throw new Error("A wire sequence must be a non-negative safe integer.");
+    }
+    if (!Number.isInteger(packet.type) || packet.type < 1 || packet.type > 18) {
+        throw new Error("Unknown remote terminal packet type.");
+    }
+    const source = Buffer.from(packet.payload);
+    const compressed = source.length >= 512 ? deflateRawSync(source) : source;
+    const useCompression = compressed.length + 16 < source.length;
+    const payload = useCompression ? compressed : source;
+    const frame = Buffer.allocUnsafe(WIRE_HEADER_BYTES + payload.length);
+    frame.writeUInt16BE(WIRE_MAGIC, 0);
+    frame.writeUInt8(WIRE_VERSION, 2);
+    frame.writeUInt8(packet.type, 3);
+    frame.writeUInt8(useCompression ? COMPRESSED : 0, 4);
+    frame.fill(0, 5, 8);
+    frame.writeBigUInt64BE(BigInt(packet.sequence), 8);
+    frame.writeUInt32BE(payload.length, 16);
+    payload.copy(frame, WIRE_HEADER_BYTES);
+    return { compressed: useCompression, data: frame, payloadBytes: source.length };
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { applyGridPatch } from "./applyGridPatch.js";
+export { diffGridState } from "./diffGridState.js";
+export { encodeWirePacket } from "./encodeWirePacket.js";
+export { createGhosttyRemoteTerminalServer, GhosttyRemoteTerminalReplica, GhosttyRemoteTerminalServerDriver, ghosttySnapshotToGrid, } from "./GhosttyRemoteTerminal.js";
+export { RemoteTerminalProtocolClient } from "./RemoteTerminalProtocolClient.js";
+export type { RemoteTerminalReconnectState } from "./RemoteTerminalProtocolClient.js";
+export { RemoteTerminalProtocolServer } from "./RemoteTerminalProtocolServer.js";
+export { WirePacketDecoder } from "./WirePacketDecoder.js";
+export { WirePacketType, type WirePacket } from "./WirePacket.js";
+export { ThrottledTcpProxy, type ThrottledTcpProxyOptions } from "./testing/ThrottledTcpProxy.js";
+export type { RemoteTerminalClientOptions, RemoteTerminalGridCell, RemoteTerminalGridPatch, RemoteTerminalGridRow, RemoteTerminalGridState, RemoteTerminalMode, RemoteTerminalProtocolMetrics, RemoteTerminalReplica, RemoteTerminalScrollbackPage, RemoteTerminalServerOptions, } from "./types.js";
+export type { GhosttySnapshot, GhosttySnapshotCell, GhosttyTerminalLike, } from "./GhosttyRemoteTerminal.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../sources/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EACH,iCAAiC,EACjC,4BAA4B,EAC5B,iCAAiC,EACjC,qBAAqB,GACxB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAC;AACjF,YAAY,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAC;AACtF,OAAO,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAC;AACjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAClG,YAAY,EACR,2BAA2B,EAC3B,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,uBAAuB,EACvB,kBAAkB,EAClB,6BAA6B,EAC7B,qBAAqB,EACrB,4BAA4B,EAC5B,2BAA2B,GAC9B,MAAM,YAAY,CAAC;AACpB,YAAY,EACR,eAAe,EACf,mBAAmB,EACnB,mBAAmB,GACtB,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export { applyGridPatch } from "./applyGridPatch.js";
+export { diffGridState } from "./diffGridState.js";
+export { encodeWirePacket } from "./encodeWirePacket.js";
+export { createGhosttyRemoteTerminalServer, GhosttyRemoteTerminalReplica, GhosttyRemoteTerminalServerDriver, ghosttySnapshotToGrid, } from "./GhosttyRemoteTerminal.js";
+export { RemoteTerminalProtocolClient } from "./RemoteTerminalProtocolClient.js";
+export { RemoteTerminalProtocolServer } from "./RemoteTerminalProtocolServer.js";
+export { WirePacketDecoder } from "./WirePacketDecoder.js";
+export { WirePacketType } from "./WirePacket.js";
+export { ThrottledTcpProxy } from "./testing/ThrottledTcpProxy.js";

package/dist/jsonPayload.d.ts

@@ -0,0 +1,3 @@
+export declare function encodeJsonPayload(value: unknown): Uint8Array;
+export declare function decodeJsonPayload<T>(value: Uint8Array): T;
+//# sourceMappingURL=jsonPayload.d.ts.map

package/dist/jsonPayload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonPayload.d.ts","sourceRoot":"","sources":["../sources/jsonPayload.ts"],"names":[],"mappings":"AAGA,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAE5D;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,GAAG,CAAC,CAEzD"}

package/dist/jsonPayload.js

@@ -0,0 +1,8 @@
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+export function encodeJsonPayload(value) {
+    return encoder.encode(JSON.stringify(value));
+}
+export function decodeJsonPayload(value) {
+    return JSON.parse(decoder.decode(value));
+}

package/dist/testing/ThrottledTcpProxy.d.ts

@@ -0,0 +1,15 @@
+export interface ThrottledTcpProxyOptions {
+    bytesPerSecond: number;
+    jitterMs?: number;
+    maxChunkBytes: number;
+    oneWayLatencyMs: number;
+    targetHost?: string;
+    targetPort: number;
+}
+export declare class ThrottledTcpProxy {
+    #private;
+    constructor(options: ThrottledTcpProxyOptions);
+    close(): Promise<void>;
+    listen(): Promise<number>;
+}
+//# sourceMappingURL=ThrottledTcpProxy.d.ts.map

package/dist/testing/ThrottledTcpProxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ThrottledTcpProxy.d.ts","sourceRoot":"","sources":["../../sources/testing/ThrottledTcpProxy.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,wBAAwB;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,iBAAiB;;gBAKd,OAAO,EAAE,wBAAwB;IAgBvC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;CA2BlC"}

package/dist/testing/ThrottledTcpProxy.js

@@ -0,0 +1,83 @@
+import { createServer, Socket } from "node:net";
+export class ThrottledTcpProxy {
+    #options;
+    #server;
+    #sockets = new Set();
+    constructor(options) {
+        if (!Number.isFinite(options.bytesPerSecond) ||
+            options.bytesPerSecond <= 0 ||
+            !Number.isSafeInteger(options.maxChunkBytes) ||
+            options.maxChunkBytes < 1 ||
+            !Number.isFinite(options.oneWayLatencyMs) ||
+            options.oneWayLatencyMs < 0 ||
+            !Number.isFinite(options.jitterMs ?? 0) ||
+            (options.jitterMs ?? 0) < 0) {
+            throw new Error("Invalid throttled TCP proxy options.");
+        }
+        this.#options = options;
+    }
+    async close() {
+        for (const socket of this.#sockets)
+            socket.destroy();
+        const server = this.#server;
+        if (server === undefined)
+            return;
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+    async listen() {
+        if (this.#server !== undefined)
+            throw new Error("The proxy is already listening.");
+        const server = createServer((client) => {
+            const upstream = new Socket();
+            this.#sockets.add(client).add(upstream);
+            client.once("close", () => this.#sockets.delete(client));
+            upstream.once("close", () => this.#sockets.delete(upstream));
+            upstream.connect(this.#options.targetPort, this.#options.targetHost ?? "127.0.0.1", () => {
+                forward(client, upstream, this.#options);
+                forward(upstream, client, this.#options);
+            });
+            client.once("error", () => upstream.destroy());
+            upstream.once("error", () => client.destroy());
+        });
+        this.#server = server;
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(0, "127.0.0.1", resolve);
+        });
+        const address = server.address();
+        if (address === null || typeof address === "string")
+            throw new Error("Missing proxy port.");
+        return address.port;
+    }
+}
+function forward(source, destination, options) {
+    const jitterMs = options.jitterMs ?? 0;
+    let packet = 0;
+    let nextAvailableAt = 0;
+    let pendingChunks = 0;
+    let sourceEnded = false;
+    const finish = () => {
+        if (sourceEnded && pendingChunks === 0 && !destination.destroyed)
+            destination.end();
+    };
+    source.on("data", (data) => {
+        for (let offset = 0; offset < data.length; offset += options.maxChunkBytes) {
+            const chunk = data.subarray(offset, offset + options.maxChunkBytes);
+            const now = performance.now();
+            const jitter = jitterMs === 0 ? 0 : (packet++ % 3) - 1;
+            const readyAt = Math.max(now + options.oneWayLatencyMs + jitter * jitterMs, nextAvailableAt);
+            nextAvailableAt = readyAt + (chunk.length / options.bytesPerSecond) * 1_000;
+            pendingChunks += 1;
+            setTimeout(() => {
+                if (!destination.destroyed)
+                    destination.write(chunk);
+                pendingChunks -= 1;
+                finish();
+            }, Math.max(0, readyAt - now)).unref();
+        }
+    });
+    source.once("end", () => {
+        sourceEnded = true;
+        finish();
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,105 @@
+import type { Duplex } from "node:stream";
+export type RemoteTerminalMode = "grid" | "vt";
+export interface RemoteTerminalGridCell {
+    styleId: number;
+    text: string;
+    width: 1 | 2;
+    x: number;
+}
+export interface RemoteTerminalGridRow {
+    cells: readonly RemoteTerminalGridCell[];
+    wrapped: boolean;
+}
+export interface RemoteTerminalGridState {
+    cols: number;
+    coversOutputOffset: number;
+    cursor: {
+        visible: boolean;
+        x: number;
+        y: number;
+    } | null;
+    palette: readonly string[];
+    revision: number;
+    rows: readonly RemoteTerminalGridRow[];
+    startRow: number;
+    styles: readonly Readonly<Record<string, unknown>>[];
+    title: string;
+    totalRows: number;
+}
+export interface RemoteTerminalGridPatch {
+    baseRevision: number;
+    cols: number;
+    coversOutputOffset: number;
+    cursor: RemoteTerminalGridState["cursor"];
+    palette: readonly string[];
+    revision: number;
+    rows: readonly (readonly [number, RemoteTerminalGridRow])[];
+    startRow: number;
+    styles: RemoteTerminalGridState["styles"];
+    title: string;
+    totalRows: number;
+}
+export interface RemoteTerminalReplica {
+    applyGrid(state: RemoteTerminalGridState): void | Promise<void>;
+    applyVt(data: Uint8Array): void | Promise<void>;
+    resize(cols: number, rows: number): void | Promise<void>;
+}
+export interface RemoteTerminalScrollbackPage {
+    baseRow: number;
+    count: number;
+    historyEpoch: string;
+    historyRevision: number;
+    palette?: readonly string[];
+    rows: readonly RemoteTerminalGridRow[];
+    start: number;
+    styles?: readonly Readonly<Record<string, unknown>>[];
+    totalRows: number;
+}
+export interface RemoteTerminalServerOptions {
+    epoch?: string;
+    initialCols?: number;
+    initialRows?: number;
+    maxBufferedBytes?: number;
+    maxInputLeases?: number;
+    maxFrameBytes?: number;
+    maxReplayBytes?: number;
+    maxUnacknowledgedBytes?: number;
+    onBeforeResize?: () => void | Promise<void>;
+    onFlowControl?: (paused: boolean) => void;
+    onInput: (data: Uint8Array) => void | Promise<void>;
+    onResize: (cols: number, rows: number) => void | Promise<void>;
+    onScrollback?: (start: number, count: number, basis?: {
+        historyEpoch: string;
+        historyRevision: number;
+    }) => RemoteTerminalScrollbackPage | Promise<RemoteTerminalScrollbackPage>;
+    parserFingerprint?: string;
+    wireChunkBytes?: number;
+}
+export interface RemoteTerminalClientOptions {
+    capabilities?: {
+        grid: boolean;
+        vt: boolean;
+    };
+    clientId: string;
+    creditBytes?: number;
+    epoch?: string;
+    inputLease?: string;
+    pendingInputs?: readonly {
+        data: Uint8Array;
+        sequence: number;
+    }[];
+    onExit?: (exitCode: number | null) => void;
+    onMode?: (mode: RemoteTerminalMode) => void;
+    parserFingerprint?: string;
+    replica: RemoteTerminalReplica;
+    resumeInputSequence?: number;
+    resumeOutputOffset?: number;
+    stream: Duplex;
+}
+export interface RemoteTerminalProtocolMetrics {
+    compressedPackets: number;
+    encodedPackets: number;
+    payloadBytes: number;
+    wireBytes: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@slopus/ghostty-web",
+  "version": "0.1.0",
+  "description": "Client/server protocol for efficiently remoting a Ghostty-backed terminal to web and native clients.",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.10",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4",
+    "@slopus/rig-gym": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}