@slopus/ghostty-web 0.1.0

package/dist/RemoteTerminalProtocolServer.js

@@ -0,0 +1,794 @@
+import { randomUUID } from "node:crypto";
+import { diffGridState } from "./diffGridState.js";
+import { encodeWirePacket } from "./encodeWirePacket.js";
+import { decodeJsonPayload, encodeJsonPayload } from "./jsonPayload.js";
+import { WirePacketDecoder } from "./WirePacketDecoder.js";
+import { WirePacketType } from "./WirePacket.js";
+export class RemoteTerminalProtocolServer {
+    epoch;
+    metrics = {
+        compressedPackets: 0,
+        encodedPackets: 0,
+        payloadBytes: 0,
+        wireBytes: 0,
+    };
+    #connections = new Set();
+    #cols;
+    #deferredBytes = 0;
+    #deferredOutput = [];
+    #deferredGrid = [];
+    #deferredUpdates = [];
+    #exit;
+    #failure;
+    #grid;
+    #gridPackets = new Map();
+    #gridRevision = 0;
+    #inputLeases = new Map();
+    #lastResizeBarrier = 0;
+    #maxInputLeases;
+    #maxBufferedBytes;
+    #maxFrameBytes;
+    #maxReplayBytes;
+    #maxUnacknowledgedBytes;
+    #options;
+    #outputChunks = [];
+    #outputOffset = 0;
+    #pausedConnections = new Set();
+    #replayBytes = 0;
+    #resizeOperation = Promise.resolve();
+    #resizeRevision = 0;
+    #resizing = false;
+    #rows;
+    #wireChunkBytes;
+    constructor(options) {
+        this.#options = options;
+        this.#maxReplayBytes = boundedInteger(options.maxReplayBytes ?? 4 * 1024 * 1024, 1, 64 * 1024 * 1024, "replay bytes");
+        this.#maxBufferedBytes = boundedInteger(options.maxBufferedBytes ?? this.#maxReplayBytes, 1, 64 * 1024 * 1024, "buffered bytes");
+        this.#maxInputLeases = boundedInteger(options.maxInputLeases ?? 1_024, 1, 65_536, "input leases");
+        this.#maxFrameBytes = boundedInteger(options.maxFrameBytes ?? 4 * 1024 * 1024, 1, 64 * 1024 * 1024, "frame bytes");
+        this.#wireChunkBytes = boundedInteger(options.wireChunkBytes ?? 16 * 1024, 1, this.#maxFrameBytes, "wire chunk bytes");
+        this.#maxUnacknowledgedBytes = boundedInteger(options.maxUnacknowledgedBytes ?? 256 * 1024, this.#wireChunkBytes, 64 * 1024 * 1024, "unacknowledged bytes");
+        this.#cols = boundedInteger(options.initialCols ?? 80, 1, 1_000, "initial columns");
+        this.#rows = boundedInteger(options.initialRows ?? 24, 1, 1_000, "initial rows");
+        this.epoch = options.epoch ?? randomUUID();
+    }
+    attach(stream) {
+        const connection = new ServerConnection(this, stream, this.#maxFrameBytes);
+        this.#connections.add(connection);
+        let removed = false;
+        const cleanup = () => {
+            if (removed)
+                return;
+            removed = true;
+            connection.close();
+            this.#connections.delete(connection);
+            this.releaseInputLease(connection);
+            this.setFlowPaused(connection, false);
+        };
+        stream.once("close", cleanup);
+        if (this.#failure !== undefined)
+            queueMicrotask(() => connection.fail(this.#failure));
+        return cleanup;
+    }
+    publishExit(exitCode) {
+        if (this.#failure !== undefined)
+            throw this.#failure;
+        if (this.#exit !== undefined)
+            return;
+        if (this.#resizing) {
+            this.#resizeOperation = this.#resizeOperation.then(() => this.publishExit(exitCode));
+            return;
+        }
+        this.#exit = { exitCode, outputOffset: this.#outputOffset };
+        for (const connection of this.#connections)
+            connection.maybeSendExit();
+    }
+    publishGrid(state) {
+        if (this.#failure !== undefined)
+            throw this.#failure;
+        if (this.#exit !== undefined)
+            throw new Error("Terminal output has already exited.");
+        if (!Number.isSafeInteger(state.coversOutputOffset) ||
+            state.coversOutputOffset < 0 ||
+            state.coversOutputOffset > this.#outputOffset) {
+            throw new Error("Grid output coverage is invalid.");
+        }
+        if (this.#resizing) {
+            this.#reserveDeferredBytes(encodeJsonPayload(state).length);
+            this.#deferredGrid.push(state);
+        }
+        else
+            this.#commitGrid(state);
+    }
+    publishOutput(data) {
+        if (this.#failure !== undefined)
+            throw this.#failure;
+        if (data.length === 0)
+            return;
+        if (this.#exit !== undefined)
+            throw new Error("Terminal output has already exited.");
+        if (this.#resizing) {
+            this.#reserveDeferredBytes(data.length);
+            this.#deferredOutput.push(Buffer.from(data));
+            return;
+        }
+        this.#commitOutput(Buffer.from(data));
+    }
+    /** Parse output into the canonical emulator first, then publish bytes and its matching grid atomically. */
+    publishUpdate(data, state) {
+        if (this.#failure !== undefined)
+            throw this.#failure;
+        if (this.#exit !== undefined)
+            throw new Error("Terminal output has already exited.");
+        if (this.#resizing) {
+            this.#reserveDeferredBytes(data.length);
+            this.#deferredUpdates.push({ data: Buffer.from(data), state });
+            return;
+        }
+        this.#commitOutput(Buffer.from(data));
+        this.#commitGrid({ ...state, coversOutputOffset: this.#outputOffset });
+    }
+    claimInputLease(requested, connection) {
+        if (requested !== undefined) {
+            validateString(requested, "input lease", 128);
+            const lease = this.#inputLeases.get(requested);
+            if (lease === undefined)
+                throw new Error("Input lease is unavailable.");
+            if (lease.active !== undefined && lease.active !== connection)
+                throw new Error("Input lease is already attached.");
+            lease.active = connection;
+            lease.lastUsed = Date.now();
+            return {
+                outputOffset: lease.outputOffset,
+                resizeRevision: lease.resizeRevision,
+                sequence: lease.sequence,
+                token: requested,
+            };
+        }
+        while (this.#inputLeases.size >= this.#maxInputLeases) {
+            const idle = [...this.#inputLeases].find(([, lease]) => lease.active === undefined);
+            if (idle === undefined)
+                throw new Error("Too many active input leases.");
+            this.#inputLeases.delete(idle[0]);
+        }
+        const token = randomUUID();
+        this.#inputLeases.set(token, {
+            active: connection,
+            lastUsed: Date.now(),
+            outputOffset: 0,
+            resizeRevision: 0,
+            sequence: 0,
+        });
+        return { outputOffset: 0, resizeRevision: 0, sequence: 0, token };
+    }
+    releaseInputLease(connection) {
+        for (const lease of this.#inputLeases.values()) {
+            if (lease.active === connection)
+                lease.active = undefined;
+        }
+    }
+    async receiveInput(token, sequence, data) {
+        if (this.#failure !== undefined)
+            throw this.#failure;
+        if (this.#exit !== undefined)
+            throw new Error("Terminal has exited.");
+        const lease = this.#inputLeases.get(token);
+        if (lease === undefined)
+            throw new Error("Input lease is unavailable.");
+        if (sequence <= lease.sequence)
+            return;
+        if (sequence !== lease.sequence + 1)
+            throw new Error("Client input sequence has a gap.");
+        await this.#options.onInput(data);
+        lease.sequence = sequence;
+        lease.lastUsed = Date.now();
+    }
+    acknowledgeOutput(token, outputOffset) {
+        const lease = this.#inputLeases.get(token);
+        if (lease === undefined)
+            throw new Error("Input lease is unavailable.");
+        lease.outputOffset = outputOffset;
+        lease.lastUsed = Date.now();
+    }
+    acknowledgeResize(token, revision) {
+        const lease = this.#inputLeases.get(token);
+        if (lease === undefined ||
+            revision < lease.resizeRevision ||
+            revision > this.#resizeRevision)
+            throw new Error("Invalid resize acknowledgement.");
+        lease.resizeRevision = revision;
+        lease.lastUsed = Date.now();
+    }
+    requestResize(requester, requestSequence, cols, rows) {
+        if (this.#failure !== undefined)
+            return Promise.reject(this.#failure);
+        if (this.#exit !== undefined)
+            return Promise.reject(new Error("Terminal has exited."));
+        validateDimensions(cols, rows);
+        const operation = this.#resizeOperation.then(async () => {
+            await this.#options.onBeforeResize?.();
+            const barrier = this.#outputOffset;
+            this.#resizing = true;
+            try {
+                await this.#options.onResize(cols, rows);
+                this.#cols = cols;
+                this.#rows = rows;
+                this.#lastResizeBarrier = barrier;
+                this.#resizeRevision += 1;
+                for (const connection of this.#connections) {
+                    connection.sendResize(cols, rows, barrier, this.#resizeRevision, connection === requester ? requestSequence : 0);
+                }
+            }
+            finally {
+                this.#resizing = false;
+                this.#flushDeferredOutput();
+            }
+        });
+        this.#resizeOperation = operation.catch(() => undefined);
+        return operation;
+    }
+    resize(cols, rows) {
+        return this.requestResize(undefined, 0, cols, rows);
+    }
+    scrollback(start, count, basis) {
+        if (this.#options.onScrollback === undefined)
+            throw new Error("Scrollback paging is unavailable.");
+        return this.#options.onScrollback(start, count, basis);
+    }
+    setFlowPaused(connection, paused) {
+        const wasPaused = this.#pausedConnections.size > 0;
+        if (paused)
+            this.#pausedConnections.add(connection);
+        else
+            this.#pausedConnections.delete(connection);
+        const isPaused = this.#pausedConnections.size > 0;
+        if (wasPaused !== isPaused)
+            this.#options.onFlowControl?.(isPaused);
+    }
+    encode(packet) {
+        if (packet.payload.length > this.#maxFrameBytes) {
+            throw new Error("Outbound remote terminal frame is too large.");
+        }
+        const encoded = encodeWirePacket(packet);
+        this.metrics.encodedPackets += 1;
+        this.metrics.payloadBytes += encoded.payloadBytes;
+        if (encoded.compressed)
+            this.metrics.compressedPackets += 1;
+        return { data: encoded.data };
+    }
+    gridPacket(grid) {
+        let packet = this.#gridPackets.get(grid.revision);
+        if (packet === undefined) {
+            packet = this.encode({
+                payload: encodeJsonPayload(grid),
+                sequence: grid.revision,
+                type: WirePacketType.GridKeyframe,
+            });
+            this.#gridPackets.set(grid.revision, packet);
+        }
+        return packet;
+    }
+    dimensions() {
+        return { cols: this.#cols, rows: this.#rows };
+    }
+    maxBufferedBytes() {
+        return this.#maxBufferedBytes;
+    }
+    exitState() {
+        return this.#exit;
+    }
+    grid() {
+        return this.#grid;
+    }
+    lastResizeBarrier() {
+        return this.#lastResizeBarrier;
+    }
+    maxUnacknowledgedBytes() {
+        return this.#maxUnacknowledgedBytes;
+    }
+    parserFingerprint() {
+        return this.#options.parserFingerprint ?? "libghostty-vt/0.2/defaults";
+    }
+    oldestOutputOffset() {
+        return this.#outputChunks[0]?.start ?? this.#outputOffset;
+    }
+    outputOffset() {
+        return this.#outputOffset;
+    }
+    resizeRevision() {
+        return this.#resizeRevision;
+    }
+    replayAfter(offset) {
+        return this.#outputChunks
+            .filter((chunk) => chunk.end > offset)
+            .map((chunk) => offset > chunk.start
+            ? this.#makeOutputChunk(chunk.data.subarray(offset - chunk.start), offset)
+            : chunk);
+    }
+    wireChunkBytes() {
+        return this.#wireChunkBytes;
+    }
+    fail(error) {
+        if (this.#failure !== undefined)
+            return;
+        this.#failure = error instanceof Error ? error : new Error(String(error));
+        for (const connection of this.#connections)
+            connection.fail(this.#failure);
+    }
+    #commitGrid(state) {
+        const previous = this.#grid;
+        const next = { ...state, revision: ++this.#gridRevision };
+        this.#grid = next;
+        this.#gridPackets.clear();
+        for (const connection of this.#connections)
+            connection.publishGrid(previous, next);
+    }
+    #commitOutput(data) {
+        if (data.length === 0)
+            return;
+        if (data.length > this.#wireChunkBytes) {
+            for (let offset = 0; offset < data.length; offset += this.#wireChunkBytes) {
+                this.#commitOutput(data.subarray(offset, offset + this.#wireChunkBytes));
+            }
+            return;
+        }
+        const chunk = this.#makeOutputChunk(data, this.#outputOffset);
+        this.#outputOffset = chunk.end;
+        this.#outputChunks.push(chunk);
+        this.#replayBytes += data.length;
+        while (this.#replayBytes > this.#maxReplayBytes && this.#outputChunks.length > 0) {
+            const removed = this.#outputChunks.shift();
+            this.#replayBytes -= removed.data.length;
+        }
+        for (const connection of this.#connections)
+            connection.publishOutput(chunk);
+    }
+    #flushDeferredOutput() {
+        const output = this.#deferredOutput.splice(0);
+        const updates = this.#deferredUpdates.splice(0);
+        const grids = this.#deferredGrid.splice(0);
+        this.#deferredBytes = 0;
+        if (this.#failure !== undefined)
+            return;
+        for (const data of output)
+            this.#commitOutput(data);
+        for (const update of updates) {
+            this.#commitOutput(update.data);
+            this.#commitGrid({ ...update.state, coversOutputOffset: this.#outputOffset });
+        }
+        for (const grid of grids)
+            this.#commitGrid(grid);
+    }
+    #reserveDeferredBytes(length) {
+        if (this.#deferredBytes + length > this.#maxBufferedBytes) {
+            throw new Error("Resize output buffer is full.");
+        }
+        this.#deferredBytes += length;
+    }
+    #makeOutputChunk(data, start) {
+        const end = start + data.length;
+        return {
+            data,
+            encoded: this.encode({ payload: data, sequence: end, type: WirePacketType.Output }),
+            end,
+            start,
+        };
+    }
+}
+class ServerConnection {
+    #acknowledgedOutput = 0;
+    #blocked = false;
+    #capabilities = { grid: false, vt: false };
+    #closed = false;
+    #creditBytes = 0;
+    #decoder;
+    #exitSent = false;
+    #gridAcknowledged;
+    #gridInFlight;
+    #initialized = false;
+    #inputLease;
+    #lastResizeRequest = 0;
+    #maxSentOutput = 0;
+    #mode = "vt";
+    #needsGridOffset;
+    #operation = Promise.resolve();
+    #pendingGrid;
+    #pendingVtBytes = 0;
+    #pendingVt = [];
+    #server;
+    #stream;
+    constructor(server, stream, maxFrameBytes) {
+        this.#server = server;
+        this.#stream = stream;
+        this.#decoder = new WirePacketDecoder(maxFrameBytes);
+        stream.on("data", (data) => {
+            try {
+                const packets = this.#decoder.push(data);
+                if (packets.length > 0)
+                    stream.pause();
+                for (const packet of packets)
+                    this.#operation = this.#operation.then(() => this.#receive(packet));
+                void this.#operation
+                    .then(() => {
+                    if (!this.#closed)
+                        stream.resume();
+                })
+                    .catch((error) => {
+                    this.#sendError(error);
+                    this.close();
+                });
+            }
+            catch (error) {
+                this.#sendError(error);
+                this.close();
+            }
+        });
+        stream.on("drain", () => this.#drain());
+        stream.on("error", () => this.close());
+        stream.on("close", () => this.close());
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#server.releaseInputLease(this);
+        this.#server.setFlowPaused(this, false);
+        this.#stream.destroy();
+    }
+    fail(error) {
+        this.#sendError(error);
+        this.close();
+    }
+    publishGrid(previous, next) {
+        if (!this.#initialized)
+            return;
+        if (this.#needsGridOffset !== undefined &&
+            this.#capabilities.grid &&
+            next.coversOutputOffset >= this.#needsGridOffset) {
+            this.#switchToGrid(next);
+            return;
+        }
+        if (this.#mode !== "grid")
+            return;
+        if (this.#blocked || this.#gridInFlight !== undefined) {
+            this.#pendingGrid = next;
+            return;
+        }
+        this.#sendGrid(previous, next);
+    }
+    publishOutput(chunk) {
+        if (!this.#initialized || this.#mode !== "vt")
+            return;
+        if (this.#needsGridOffset !== undefined) {
+            this.#needsGridOffset = chunk.end;
+            if (!this.#capabilities.grid)
+                this.#queueVt(chunk);
+            return;
+        }
+        if (chunk.end - this.#acknowledgedOutput > this.#creditBytes) {
+            this.#needsGridOffset = chunk.end;
+            if (this.#capabilities.grid) {
+                const grid = this.#server.grid();
+                if (grid !== undefined && grid.coversOutputOffset >= chunk.end)
+                    this.#switchToGrid(grid);
+            }
+            else {
+                this.#queueVt(chunk);
+                this.#server.setFlowPaused(this, true);
+            }
+            return;
+        }
+        this.#sendOutput(chunk);
+    }
+    sendResize(cols, rows, barrier, resizeRevision, requestSequence) {
+        this.#sendPacket({
+            payload: encodeJsonPayload({ barrier, cols, requestSequence, resizeRevision, rows }),
+            sequence: barrier,
+            type: WirePacketType.ResizeAck,
+        });
+    }
+    maybeSendExit() {
+        const exit = this.#server.exitState();
+        if (exit === undefined || this.#exitSent || !this.#initialized)
+            return;
+        if (this.#mode === "vt") {
+            if (this.#needsGridOffset !== undefined || this.#maxSentOutput < exit.outputOffset)
+                return;
+        }
+        else if ((this.#gridAcknowledged?.coversOutputOffset ?? -1) < exit.outputOffset) {
+            const grid = this.#server.grid();
+            if (grid !== undefined &&
+                grid.coversOutputOffset >= exit.outputOffset &&
+                this.#gridInFlight === undefined)
+                this.#sendGridKeyframe(grid);
+            return;
+        }
+        this.#sendPacket({
+            payload: encodeJsonPayload(exit),
+            sequence: exit.outputOffset,
+            type: WirePacketType.Exit,
+        });
+        this.#exitSent = true;
+    }
+    #drain() {
+        this.#blocked = false;
+        this.#flushGrid();
+    }
+    async #initialize(packet) {
+        if (packet.type !== WirePacketType.ClientHello)
+            throw new Error("Client hello is required.");
+        if (packet.payload.length > 4_096)
+            throw new Error("Client hello is too large.");
+        const hello = decodeJsonPayload(packet.payload);
+        validateHello(hello);
+        const lease = this.#server.claimInputLease(hello.inputLease, this);
+        this.#inputLease = lease.token;
+        this.#capabilities = hello.capabilities;
+        this.#creditBytes = Math.min(hello.creditBytes, this.#server.maxUnacknowledgedBytes());
+        if (hello.creditBytes < this.#server.wireChunkBytes()) {
+            throw new Error("Client credit is smaller than the server wire chunk.");
+        }
+        const epochMatches = (hello.epoch === undefined && hello.resumeOutputOffset === 0) ||
+            hello.epoch === this.#server.epoch;
+        const freshReplay = hello.inputLease === undefined &&
+            hello.epoch === undefined &&
+            hello.resumeOutputOffset === 0 &&
+            this.#server.resizeRevision() === 0;
+        const leasedReplay = hello.inputLease !== undefined &&
+            epochMatches &&
+            hello.resumeOutputOffset === lease.outputOffset &&
+            lease.resizeRevision === this.#server.resizeRevision();
+        const canReplay = hello.capabilities.vt &&
+            hello.parserFingerprint === this.#server.parserFingerprint() &&
+            (freshReplay || leasedReplay) &&
+            hello.resumeOutputOffset >= this.#server.oldestOutputOffset() &&
+            hello.resumeOutputOffset <= this.#server.outputOffset();
+        if (!canReplay && !hello.capabilities.grid)
+            throw new Error("Terminal replay is unavailable.");
+        this.#mode = canReplay ? "vt" : "grid";
+        this.#acknowledgedOutput = canReplay ? hello.resumeOutputOffset : 0;
+        const dimensions = this.#server.dimensions();
+        this.#sendPacket({
+            payload: encodeJsonPayload({
+                ...dimensions,
+                epoch: this.#server.epoch,
+                gridRevision: this.#server.grid()?.revision ?? 0,
+                inputLease: lease.token,
+                inputSequence: lease.sequence,
+                resizeRevision: this.#server.resizeRevision(),
+                mode: this.#mode,
+                oldestOutputOffset: this.#server.oldestOutputOffset(),
+                outputOffset: this.#server.outputOffset(),
+            }),
+            sequence: this.#server.outputOffset(),
+            type: WirePacketType.Welcome,
+        });
+        this.#initialized = true;
+        if (this.#mode === "vt") {
+            for (const chunk of this.#server.replayAfter(hello.resumeOutputOffset))
+                this.publishOutput(chunk);
+            const grid = this.#server.grid();
+            if (this.#needsGridOffset !== undefined &&
+                grid !== undefined &&
+                grid.coversOutputOffset >= this.#needsGridOffset)
+                this.#switchToGrid(grid);
+        }
+        else {
+            const grid = this.#server.grid();
+            if (grid === undefined || grid.coversOutputOffset < this.#server.outputOffset())
+                throw new Error("A current semantic terminal keyframe is unavailable.");
+            this.#sendGridKeyframe(grid);
+        }
+        this.maybeSendExit();
+    }
+    async #receive(packet) {
+        if (!this.#initialized)
+            return this.#initialize(packet);
+        if (packet.type === WirePacketType.OutputAck) {
+            if (packet.payload.length !== 0 ||
+                packet.sequence < this.#acknowledgedOutput ||
+                packet.sequence > this.#maxSentOutput)
+                throw new Error("Invalid output acknowledgement.");
+            this.#acknowledgedOutput = packet.sequence;
+            this.#server.acknowledgeOutput(this.#inputLease, packet.sequence);
+            this.#flushPendingVt();
+            this.maybeSendExit();
+            return;
+        }
+        if (packet.type === WirePacketType.GridAck) {
+            if (packet.payload.length !== 0 ||
+                this.#gridInFlight === undefined ||
+                packet.sequence !== this.#gridInFlight.revision)
+                throw new Error("Invalid grid acknowledgement.");
+            this.#gridAcknowledged = this.#gridInFlight;
+            this.#gridInFlight = undefined;
+            this.#flushGrid();
+            this.maybeSendExit();
+            return;
+        }
+        if (packet.type === WirePacketType.Input) {
+            if (packet.payload.length > 64 * 1024)
+                throw new Error("Terminal input is too large.");
+            await this.#server.receiveInput(this.#inputLease, packet.sequence, packet.payload);
+            this.#sendPacket({
+                payload: Buffer.alloc(0),
+                sequence: packet.sequence,
+                type: WirePacketType.InputAck,
+            });
+            return;
+        }
+        if (packet.type === WirePacketType.Resize) {
+            if (packet.payload.length > 1_024 || packet.sequence !== this.#lastResizeRequest + 1)
+                throw new Error("Invalid resize sequence.");
+            this.#lastResizeRequest = packet.sequence;
+            const value = decodeJsonPayload(packet.payload);
+            await this.#server.requestResize(this, packet.sequence, value.cols, value.rows);
+            return;
+        }
+        if (packet.type === WirePacketType.ResizeApplied) {
+            if (packet.payload.length !== 0)
+                throw new Error("Invalid resize acknowledgement.");
+            this.#server.acknowledgeResize(this.#inputLease, packet.sequence);
+            return;
+        }
+        if (packet.type === WirePacketType.Resync) {
+            if (packet.payload.length !== 0)
+                throw new Error("Invalid resync request.");
+            const grid = this.#server.grid();
+            if (grid === undefined || grid.coversOutputOffset < this.#server.outputOffset())
+                throw new Error("A current semantic terminal keyframe is unavailable.");
+            this.#switchToGrid(grid);
+            return;
+        }
+        if (packet.type === WirePacketType.ScrollbackRequest) {
+            if (packet.payload.length > 1_024)
+                throw new Error("Scrollback request is too large.");
+            const value = decodeJsonPayload(packet.payload);
+            validateScrollbackRequest(value);
+            const page = await this.#server.scrollback(value.start, value.count, value.basis);
+            validateScrollbackPage(page, value.start, value.count);
+            this.#sendPacket({
+                payload: encodeJsonPayload(page),
+                sequence: packet.sequence,
+                type: WirePacketType.ScrollbackPage,
+            });
+            return;
+        }
+        throw new Error("Packet is invalid in the current server state.");
+    }
+    #flushGrid() {
+        const grid = this.#pendingGrid;
+        if (grid !== undefined && !this.#blocked && this.#gridInFlight === undefined) {
+            this.#pendingGrid = undefined;
+            this.#sendGridKeyframe(grid);
+        }
+    }
+    #flushPendingVt() {
+        while (this.#pendingVt.length > 0) {
+            const next = this.#pendingVt[0];
+            if (next.end - this.#acknowledgedOutput > this.#creditBytes)
+                break;
+            this.#pendingVt.shift();
+            this.#pendingVtBytes -= next.data.length;
+            this.#sendOutput(next);
+        }
+        if (this.#pendingVt.length === 0) {
+            this.#needsGridOffset = undefined;
+            this.#server.setFlowPaused(this, false);
+        }
+    }
+    #queueVt(chunk) {
+        if (this.#pendingVtBytes + chunk.data.length > this.#server.maxBufferedBytes()) {
+            this.fail(new Error("Client terminal output buffer is full."));
+            return;
+        }
+        this.#pendingVt.push(chunk);
+        this.#pendingVtBytes += chunk.data.length;
+    }
+    #sendEncoded(packet) {
+        if (this.#closed)
+            return;
+        this.#server.metrics.wireBytes += packet.data.length;
+        this.#blocked ||= !this.#stream.write(packet.data);
+    }
+    #sendPacket(packet) {
+        this.#sendEncoded(this.#server.encode(packet));
+    }
+    #sendError(error) {
+        this.#sendPacket({
+            payload: encodeJsonPayload({
+                error: error instanceof Error ? error.message : String(error),
+            }),
+            sequence: 0,
+            type: WirePacketType.Error,
+        });
+    }
+    #sendGrid(previous, grid) {
+        const base = this.#gridAcknowledged;
+        const patch = base === undefined || previous?.revision !== base.revision
+            ? undefined
+            : diffGridState(base, grid);
+        if (patch === undefined)
+            this.#sendEncoded(this.#server.gridPacket(grid));
+        else
+            this.#sendPacket({
+                payload: encodeJsonPayload(patch),
+                sequence: grid.revision,
+                type: WirePacketType.GridPatch,
+            });
+        this.#gridInFlight = grid;
+    }
+    #sendGridKeyframe(grid) {
+        this.#sendEncoded(this.#server.gridPacket(grid));
+        this.#gridInFlight = grid;
+    }
+    #sendOutput(chunk) {
+        this.#sendEncoded(chunk.encoded);
+        this.#maxSentOutput = Math.max(this.#maxSentOutput, chunk.end);
+    }
+    #switchToGrid(grid) {
+        if (this.#gridInFlight !== undefined)
+            this.#pendingGrid = grid;
+        this.#mode = "grid";
+        this.#needsGridOffset = undefined;
+        this.#pendingVt.length = 0;
+        this.#pendingVtBytes = 0;
+        this.#server.setFlowPaused(this, false);
+        this.#sendPacket({
+            payload: encodeJsonPayload({ mode: "grid" }),
+            sequence: grid.revision,
+            type: WirePacketType.Mode,
+        });
+        if (this.#gridInFlight === undefined)
+            this.#sendGridKeyframe(grid);
+    }
+}
+function boundedInteger(value, minimum, maximum, name) {
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum)
+        throw new Error(`Invalid ${name}.`);
+    return value;
+}
+function validateDimensions(cols, rows) {
+    boundedInteger(cols, 1, 1_000, "terminal columns");
+    boundedInteger(rows, 1, 1_000, "terminal rows");
+}
+function validateString(value, name, maximumLength) {
+    if (typeof value !== "string" || value.length < 1 || value.length > maximumLength)
+        throw new Error(`Invalid ${name}.`);
+}
+function validateHello(hello) {
+    if (typeof hello !== "object" || hello === null)
+        throw new Error("Invalid client hello.");
+    validateString(hello.clientId, "client identifier", 128);
+    validateString(hello.parserFingerprint, "parser fingerprint", 256);
+    boundedInteger(hello.creditBytes, 1, 64 * 1024 * 1024, "client credit");
+    boundedInteger(hello.resumeOutputOffset, 0, Number.MAX_SAFE_INTEGER, "resume output offset");
+    if (hello.epoch !== undefined)
+        validateString(hello.epoch, "terminal epoch", 128);
+    if (typeof hello.capabilities !== "object" ||
+        hello.capabilities === null ||
+        typeof hello.capabilities.grid !== "boolean" ||
+        typeof hello.capabilities.vt !== "boolean" ||
+        (!hello.capabilities.grid && !hello.capabilities.vt))
+        throw new Error("Invalid client capabilities.");
+}
+function validateScrollbackRequest(value) {
+    boundedInteger(value.start, 0, Number.MAX_SAFE_INTEGER, "scrollback start");
+    boundedInteger(value.count, 1, 1_000, "scrollback count");
+    if (value.basis !== undefined) {
+        validateString(value.basis.historyEpoch, "history epoch", 128);
+        boundedInteger(value.basis.historyRevision, 0, Number.MAX_SAFE_INTEGER, "history revision");
+    }
+}
+function validateScrollbackPage(page, start, count) {
+    validateString(page.historyEpoch, "history epoch", 128);
+    boundedInteger(page.historyRevision, 0, Number.MAX_SAFE_INTEGER, "history revision");
+    boundedInteger(page.baseRow, 0, Number.MAX_SAFE_INTEGER, "history base row");
+    boundedInteger(page.start, 0, Number.MAX_SAFE_INTEGER, "scrollback page start");
+    boundedInteger(page.totalRows, 0, Number.MAX_SAFE_INTEGER, "scrollback total rows");
+    if (page.start !== start ||
+        page.count !== count ||
+        !Array.isArray(page.rows) ||
+        page.rows.length > count)
+        throw new Error("Invalid scrollback page.");
+}