import { describe, expect, it } from "vite-plus/test";
import { EnvironmentId, TerminalSessionSnapshot, ThreadId } from "@t3tools/contracts";
import {
applyTerminalAttachStreamEvent,
applyTerminalMetadataStreamEvent,
combineTerminalSessionState,
EMPTY_TERMINAL_BUFFER_STATE,
INITIAL_TERMINAL_OUTPUT_CURSOR,
nextTerminalAttachSeedState,
readTerminalOutputUpdate,
terminalOutputText,
} from "./terminalSession.ts";
const TARGET = {
environmentId: EnvironmentId.make("env-local"),
threadId: ThreadId.make("thread-1"),
terminalId: "term-1",
} as const;
const BASE_SNAPSHOT: TerminalSessionSnapshot = {
threadId: TARGET.threadId,
terminalId: TARGET.terminalId,
cwd: "/repo",
worktreePath: null,
status: "running",
pid: 123,
history: "hello",
exitCode: null,
exitSignal: null,
label: "Terminal 1",
updatedAt: "2026-04-01T00:00:00.000Z",
};
describe("terminal session reducers", () => {
it("prefers live attach status over stale metadata after the attach stream starts", () => {
const summary = applyTerminalMetadataStreamEvent([], {
type: "snapshot",
terminals: [
{
threadId: BASE_SNAPSHOT.threadId,
terminalId: BASE_SNAPSHOT.terminalId,
cwd: BASE_SNAPSHOT.cwd,
worktreePath: BASE_SNAPSHOT.worktreePath,
status: "running",
pid: BASE_SNAPSHOT.pid,
exitCode: BASE_SNAPSHOT.exitCode,
exitSignal: BASE_SNAPSHOT.exitSignal,
updatedAt: BASE_SNAPSHOT.updatedAt,
hasRunningSubprocess: false,
label: BASE_SNAPSHOT.label,
},
],
})[0]!;
const attached = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {
type: "error",
threadId: TARGET.threadId,
terminalId: TARGET.terminalId,
message: "Terminal disconnected.",
});
expect(combineTerminalSessionState(summary, attached)).toMatchObject({
status: "error",
error: "Terminal disconnected.",
version: 1,
});
});
it("follows the shared PTY grid from snapshots and activity without disturbing output", () => {
const attached = applyTerminalAttachStreamEvent(nextTerminalAttachSeedState(), {
type: "snapshot",
snapshot: { ...BASE_SNAPSHOT, cols: 130, rows: 15 },
});
const activity = {
type: "activity",
threadId: TARGET.threadId,
terminalId: TARGET.terminalId,
hasRunningSubprocess: false,
label: "Terminal 1",
} as const;
const narrowed = applyTerminalAttachStreamEvent(attached, { ...activity, cols: 54, rows: 15 });
// Activity from a server without geometry, or a repeat, must not reset the renderer.
const unchanged = applyTerminalAttachStreamEvent(
applyTerminalAttachStreamEvent(narrowed, activity),
{ ...activity, cols: 54, rows: 15 },
);
expect(attached.grid).toEqual({ cols: 130, rows: 15 });
expect(narrowed).toEqual({ ...attached, grid: { cols: 54, rows: 15 } });
expect(unchanged).toBe(narrowed);
});
it("preserves a BOM code point at a new output chunk boundary", () => {
const initial = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {
type: "snapshot",
snapshot: { ...BASE_SNAPSHOT, history: "" },
});
const cursor = readTerminalOutputUpdate(initial.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;
const data = `${"x".repeat(16_384)}\uFEFF${"y".repeat(20)}`;
const state = applyTerminalAttachStreamEvent(initial, {
type: "output",
threadId: TARGET.threadId,
terminalId: TARGET.terminalId,
data,
});
expect(terminalOutputText(state.output)).toBe(data);
expect(readTerminalOutputUpdate(state.output, cursor)).toMatchObject({ type: "append", data });
expect(state.output.retainedBytes).toBe(new TextEncoder().encode(data).byteLength);
});
it("preserves a leading BOM in the retained snapshot tail", () => {
const state = applyTerminalAttachStreamEvent(
EMPTY_TERMINAL_BUFFER_STATE,
{ type: "snapshot", snapshot: { ...BASE_SNAPSHOT, history: "discard\uFEFFtail" } },
7,
);
expect(terminalOutputText(state.output)).toBe("\uFEFFtail");
expect(state.output.retainedBytes).toBe(7);
});
it("trims whole Unicode code points from a partially retained chunk", () => {
let state = applyTerminalAttachStreamEvent(
EMPTY_TERMINAL_BUFFER_STATE,
{ type: "snapshot", snapshot: { ...BASE_SNAPSHOT, history: "é界🙂end" } },
12,
);
let cursor = readTerminalOutputUpdate(state.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;
for (const [data, expected, retainedBytes] of [
["x", "界🙂endx", 11],
["yz", "🙂endxyz", 10],
["abc", "endxyzabc", 9],
] as const) {
state = applyTerminalAttachStreamEvent(
state,
{ type: "output", threadId: TARGET.threadId, terminalId: TARGET.terminalId, data },
12,
);
const update = readTerminalOutputUpdate(state.output, cursor);
expect(update).toMatchObject({ type: "append", data });
expect(terminalOutputText(state.output)).toBe(expected);
expect(state.output.retainedBytes).toBe(retainedBytes);
cursor = update.cursor;
}
});
it("delivers all output when several events arrive before a renderer reads", () => {
const initial = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {
type: "snapshot",
snapshot: BASE_SNAPSHOT,
});
const cursor = readTerminalOutputUpdate(initial.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;
let state = initial;
for (const data of [" one", " two", " three"]) {
state = applyTerminalAttachStreamEvent(state, {
type: "output",
threadId: TARGET.threadId,
terminalId: TARGET.terminalId,
data,
});
}
const update = readTerminalOutputUpdate(state.output, cursor);
expect(update).toMatchObject({ type: "append", data: " one two three" });
expect(readTerminalOutputUpdate(state.output, update.cursor).type).toBe("none");
});
it("bounds historical chunk inspection when reading new tail output", () => {
let state = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {
type: "snapshot",
snapshot: { ...BASE_SNAPSHOT, history: "" },
});
for (let index = 0; index < 512; index += 1) {
state = applyTerminalAttachStreamEvent(state, {
type: "output",
threadId: TARGET.threadId,
terminalId: TARGET.terminalId,
data: "history\r\n",
});
}
const cursor = readTerminalOutputUpdate(state.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;
const next = applyTerminalAttachStreamEvent(state, {
type: "output",
threadId: TARGET.threadId,
terminalId: TARGET.terminalId,
data: "latest\r\n",
});
let historicalChunkReads = 0;
const chunks = next.output.chunks.map((chunk, index) =>
index < state.output.chunks.length
? {
...chunk,
get startOffset() {
historicalChunkReads += 1;
return chunk.startOffset;
},
}
: chunk,
);
expect(readTerminalOutputUpdate({ ...next.output, chunks }, cursor)).toMatchObject({
type: "append",
data: "latest\r\n",
});
expect(historicalChunkReads).toBeLessThanOrEqual(2);
});
it("preserves the byte-limited tail and resets a cursor before a partially trimmed chunk", () => {
const initial = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {
type: "snapshot",
snapshot: { ...BASE_SNAPSHOT, history: "" },
});
const staleCursor = readTerminalOutputUpdate(
initial.output,
INITIAL_TERMINAL_OUTPUT_CURSOR,
).cursor;
const first = applyTerminalAttachStreamEvent(initial, {
type: "output",
threadId: TARGET.threadId,
terminalId: TARGET.terminalId,
data: "hello",
});
const caughtUpCursor = readTerminalOutputUpdate(first.output, staleCursor).cursor;
const state = applyTerminalAttachStreamEvent(
first,
{ type: "output", threadId: TARGET.threadId, terminalId: TARGET.terminalId, data: " world" },
8,
);
expect(readTerminalOutputUpdate(state.output, caughtUpCursor)).toMatchObject({
type: "append",
data: " world",
});
expect(readTerminalOutputUpdate(state.output, staleCursor)).toMatchObject({
type: "reset",
data: "lo world",
});
expect(state.output.retainedBytes).toBe(8);
});
it("resets for repeated snapshots, clear, and restart even when output text repeats", () => {
let state = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {
type: "snapshot",
snapshot: BASE_SNAPSHOT,
});
let cursor = readTerminalOutputUpdate(state.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;
const attachedGeneration = state.output.generation;
// A socket reconnect resubscribes the same stream, so the server's new snapshot gets no seed.
state = applyTerminalAttachStreamEvent(state, { type: "snapshot", snapshot: BASE_SNAPSHOT });
const repeated = readTerminalOutputUpdate(state.output, cursor);
expect(repeated).toMatchObject({ type: "reset", data: "hello" });
expect(state.version).toBe(2);
// Viewers replay their measured grid once per generation; the new attachment holds the old size.
expect(state.output.generation).not.toBe(attachedGeneration);
cursor = repeated.cursor;
state = applyTerminalAttachStreamEvent(state, {
type: "cleared",
threadId: TARGET.threadId,
terminalId: TARGET.terminalId,
});
const cleared = readTerminalOutputUpdate(state.output, cursor);
expect(cleared).toMatchObject({ type: "reset", data: "" });
state = applyTerminalAttachStreamEvent(state, {
type: "restarted",
threadId: TARGET.threadId,
terminalId: TARGET.terminalId,
snapshot: BASE_SNAPSHOT,
});
expect(readTerminalOutputUpdate(state.output, cleared.cursor)).toMatchObject({
type: "reset",
data: "hello",
});
expect(state.lifecycleVersion).toBe(2);
});
it("does not reuse a renderer cursor when a fresh attach has matching counters", () => {
const first = applyTerminalAttachStreamEvent(nextTerminalAttachSeedState(), {
type: "snapshot",
snapshot: BASE_SNAPSHOT,
});
const cursor = readTerminalOutputUpdate(first.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;
const next = applyTerminalAttachStreamEvent(nextTerminalAttachSeedState(), {
type: "snapshot",
snapshot: { ...BASE_SNAPSHOT, history: "other" },
});
expect(next.output.resetVersion).toBe(first.output.resetVersion);
expect(next.output.nextOffset).toBe(first.output.nextOffset);
expect(readTerminalOutputUpdate(next.output, cursor)).toMatchObject({
type: "reset",
data: "other",
});
expect(next.lifecycleVersion).toBe(0);
});
it("appends every unread character across a compaction boundary", () => {
let state = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {
type: "snapshot",
snapshot: { ...BASE_SNAPSHOT, history: "" },
});
let cursor = readTerminalOutputUpdate(state.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;
const writes = Array.from({ length: 1200 }, (_, index) => ["x", "é", "界", "🙂"][index % 4]!);
for (const [index, data] of writes.entries()) {
state = applyTerminalAttachStreamEvent(state, {
type: "output",
threadId: TARGET.threadId,
terminalId: TARGET.terminalId,
data,
});
if (index === 99) cursor = readTerminalOutputUpdate(state.output, cursor).cursor;
}
expect(readTerminalOutputUpdate(state.output, cursor)).toMatchObject({
type: "append",
data: writes.slice(100).join(""),
});
});
});