@termlink/terminal 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bert Shim
+
+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,12 @@
+# @termlink/terminal
+
+A shell in a PTY with a headless screen for reconnects. `createTerminal()` starts the
+user's shell (PowerShell on Windows, `$SHELL` elsewhere), streams its bytes, keeps a copy
+of the screen and scrollback with `@xterm/headless`, and can hand a late client the
+current screen as bytes to write after a reset.
+
+The PTY comes from `@lydell/node-pty`, a prebuilt binary per platform installed as an
+optional dependency: nothing is compiled on the user's machine. On a platform without one,
+`ptyStatus()` says so and `createTerminal()` throws `PtyUnavailableError`.
+
+Used by `@termlink/cli`. Knows nothing about hosts, relays or clients.

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createTerminal, terminalEnv, type Terminal, type TerminalExit, type TerminalOptions } from "./terminal.js";
+export { PtyUnavailableError, ptyStatus } from "./pty.js";
+export { defaultShell, type ShellCommand } from "./shell.js";
+export { Screen } from "./screen.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AACpH,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createTerminal, terminalEnv } from "./terminal.js";
+export { PtyUnavailableError, ptyStatus } from "./pty.js";
+export { defaultShell } from "./shell.js";
+export { Screen } from "./screen.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,WAAW,EAA0D,MAAM,eAAe,CAAC;AACpH,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAqB,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/pty.d.ts

@@ -0,0 +1,19 @@
+import type * as NodePty from "@lydell/node-pty";
+export type PtyModule = typeof NodePty;
+export type { IPty } from "@lydell/node-pty";
+/** The PTY binary for this platform is missing. The host runs without terminals then. */
+export declare class PtyUnavailableError extends Error {
+    constructor(message: string);
+}
+/**
+ * Loads @lydell/node-pty once. It ships a prebuilt binary per platform as an optional
+ * dependency, so nothing is compiled on the user's machine; on an unsupported platform
+ * (or an install that skipped optional dependencies) the require fails and the error
+ * says so.
+ */
+export declare function loadPty(): PtyModule;
+export declare function ptyStatus(): {
+    available: boolean;
+    detail: string | null;
+};
+//# sourceMappingURL=pty.d.ts.map

package/dist/pty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pty.d.ts","sourceRoot":"","sources":["../src/pty.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,OAAO,MAAM,kBAAkB,CAAC;AAEjD,MAAM,MAAM,SAAS,GAAG,OAAO,OAAO,CAAC;AACvC,YAAY,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C,yFAAyF;AACzF,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAKD;;;;;GAKG;AACH,wBAAgB,OAAO,IAAI,SAAS,CAInC;AAED,wBAAgB,SAAS,IAAI;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAGzE"}

package/dist/pty.js

@@ -0,0 +1,36 @@
+import { createRequire } from "node:module";
+/** The PTY binary for this platform is missing. The host runs without terminals then. */
+export class PtyUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PtyUnavailableError";
+    }
+}
+const require = createRequire(import.meta.url);
+let loaded = null;
+/**
+ * Loads @lydell/node-pty once. It ships a prebuilt binary per platform as an optional
+ * dependency, so nothing is compiled on the user's machine; on an unsupported platform
+ * (or an install that skipped optional dependencies) the require fails and the error
+ * says so.
+ */
+export function loadPty() {
+    loaded ??= tryLoad();
+    if ("error" in loaded)
+        throw new PtyUnavailableError(loaded.error);
+    return loaded.module;
+}
+export function ptyStatus() {
+    loaded ??= tryLoad();
+    return "error" in loaded ? { available: false, detail: loaded.error } : { available: true, detail: null };
+}
+function tryLoad() {
+    try {
+        return { module: require("@lydell/node-pty") };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message.split("\n")[0] ?? err.message : String(err);
+        return { error: `terminal support is not available on ${process.platform}-${process.arch}: ${message}` };
+    }
+}
+//# sourceMappingURL=pty.js.map

package/dist/pty.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pty.js","sourceRoot":"","sources":["../src/pty.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAM5C,yFAAyF;AACzF,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,IAAI,MAAM,GAAqD,IAAI,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,UAAU,OAAO;IACrB,MAAM,KAAK,OAAO,EAAE,CAAC;IACrB,IAAI,OAAO,IAAI,MAAM;QAAE,MAAM,IAAI,mBAAmB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACnE,OAAO,MAAM,CAAC,MAAM,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,MAAM,KAAK,OAAO,EAAE,CAAC;IACrB,OAAO,OAAO,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAC5G,CAAC;AAED,SAAS,OAAO;IACd,IAAI,CAAC;QACH,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAc,EAAE,CAAC;IAC9D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC/F,OAAO,EAAE,KAAK,EAAE,wCAAwC,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,EAAE,EAAE,CAAC;IAC3G,CAAC;AACH,CAAC"}

package/dist/screen.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A headless copy of what the user's terminal shows. Every byte the shell writes goes
+ * through here too, so a client that attaches later can be given the current screen
+ * and scrollback instead of nothing. Pure JavaScript; the same on every platform.
+ */
+export declare class Screen {
+    #private;
+    constructor(cols: number, rows: number, scrollback: number);
+    get cols(): number;
+    get rows(): number;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    /** Waits for everything written so far to be parsed. */
+    flush(): Promise<void>;
+    /**
+     * The screen and scrollback as bytes a terminal can write after a reset to look the
+     * same: text, colors, cursor position.
+     */
+    snapshot(): Promise<string>;
+    dispose(): void;
+}
+//# sourceMappingURL=screen.d.ts.map

package/dist/screen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen.d.ts","sourceRoot":"","sources":["../src/screen.ts"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,qBAAa,MAAM;;IAKjB,YAAY,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAKzD;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAExB;IAED,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAEvC;IAED,wDAAwD;IACxD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAErB;IAED;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAGhC;IAED,OAAO,IAAI,IAAI,CAEd;CACF"}

package/dist/screen.js

@@ -0,0 +1,50 @@
+import { createRequire } from "node:module";
+// Both are CommonJS bundles; a plain require works everywhere the ESM named-export
+// detection might not.
+const require = createRequire(import.meta.url);
+const { Terminal: HeadlessTerminal } = require("@xterm/headless");
+const { SerializeAddon } = require("@xterm/addon-serialize");
+/**
+ * A headless copy of what the user's terminal shows. Every byte the shell writes goes
+ * through here too, so a client that attaches later can be given the current screen
+ * and scrollback instead of nothing. Pure JavaScript; the same on every platform.
+ */
+export class Screen {
+    #terminal;
+    #serializer;
+    #scrollback;
+    constructor(cols, rows, scrollback) {
+        this.#scrollback = scrollback;
+        this.#terminal = new HeadlessTerminal({ cols, rows, scrollback, allowProposedApi: true });
+        this.#serializer = new SerializeAddon();
+        this.#terminal.loadAddon(this.#serializer);
+    }
+    get cols() {
+        return this.#terminal.cols;
+    }
+    get rows() {
+        return this.#terminal.rows;
+    }
+    write(data) {
+        this.#terminal.write(data);
+    }
+    resize(cols, rows) {
+        this.#terminal.resize(cols, rows);
+    }
+    /** Waits for everything written so far to be parsed. */
+    flush() {
+        return new Promise((resolve) => this.#terminal.write("", resolve));
+    }
+    /**
+     * The screen and scrollback as bytes a terminal can write after a reset to look the
+     * same: text, colors, cursor position.
+     */
+    async snapshot() {
+        await this.flush();
+        return this.#serializer.serialize({ scrollback: this.#scrollback });
+    }
+    dispose() {
+        this.#terminal.dispose();
+    }
+}
+//# sourceMappingURL=screen.js.map

package/dist/screen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen.js","sourceRoot":"","sources":["../src/screen.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,mFAAmF;AACnF,uBAAuB;AACvB,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAqC,CAAC;AACtG,MAAM,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,wBAAwB,CAA4C,CAAC;AAExG;;;;GAIG;AACH,MAAM,OAAO,MAAM;IACR,SAAS,CAAwC;IACjD,WAAW,CAAsC;IACjD,WAAW,CAAS;IAE7B,YAAY,IAAY,EAAE,IAAY,EAAE,UAAkB;QACxD,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC;QAC9B,IAAI,CAAC,SAAS,GAAG,IAAI,gBAAgB,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1F,IAAI,CAAC,WAAW,GAAG,IAAI,cAAc,EAAE,CAAC;QACxC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC7C,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;IAC7B,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,IAAY;QAChB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,MAAM,CAAC,IAAY,EAAE,IAAY;QAC/B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,wDAAwD;IACxD,KAAK;QACH,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;IACrE,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,QAAQ;QACZ,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;QACnB,OAAO,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IACtE,CAAC;IAED,OAAO;QACL,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;CACF"}

package/dist/shell.d.ts

@@ -0,0 +1,11 @@
+export interface ShellCommand {
+    file: string;
+    args: string[];
+}
+/**
+ * The shell a terminal session runs when none is configured: like an ssh login, the
+ * user's own shell. Windows prefers PowerShell 7 (pwsh), then Windows PowerShell,
+ * then cmd. Elsewhere $SHELL, then bash, then sh, as a login shell.
+ */
+export declare function defaultShell(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): ShellCommand;
+//# sourceMappingURL=shell.d.ts.map

package/dist/shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../src/shell.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,kBAAmB,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,CAe5G"}

package/dist/shell.js

@@ -0,0 +1,37 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+/**
+ * The shell a terminal session runs when none is configured: like an ssh login, the
+ * user's own shell. Windows prefers PowerShell 7 (pwsh), then Windows PowerShell,
+ * then cmd. Elsewhere $SHELL, then bash, then sh, as a login shell.
+ */
+export function defaultShell(platform = process.platform, env = process.env) {
+    if (platform === "win32") {
+        const pwsh = findOnPath("pwsh.exe", env);
+        if (pwsh)
+            return { file: pwsh, args: ["-NoLogo"] };
+        const system = env.SystemRoot ?? env.windir ?? "C:\\Windows";
+        const powershell = path.join(system, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+        if (existsSync(powershell))
+            return { file: powershell, args: ["-NoLogo"] };
+        return { file: path.join(system, "System32", "cmd.exe"), args: [] };
+    }
+    const own = env.SHELL;
+    if (own && existsSync(own))
+        return { file: own, args: ["-l"] };
+    for (const candidate of ["/bin/bash", "/usr/bin/bash", "/bin/zsh", "/bin/sh"]) {
+        if (existsSync(candidate))
+            return { file: candidate, args: ["-l"] };
+    }
+    return { file: "sh", args: ["-l"] };
+}
+function findOnPath(name, env) {
+    const entries = (env.PATH ?? env.Path ?? "").split(path.delimiter).filter(Boolean);
+    for (const dir of entries) {
+        const candidate = path.join(dir, name);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+//# sourceMappingURL=shell.js.map

package/dist/shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../src/shell.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,IAAI,MAAM,WAAW,CAAC;AAO7B;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,EAAE,GAAG,GAAsB,OAAO,CAAC,GAAG;IAC5F,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,UAAU,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;QACzC,IAAI,IAAI;YAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC;QACnD,MAAM,MAAM,GAAG,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,MAAM,IAAI,aAAa,CAAC;QAC7D,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC;QAChG,IAAI,UAAU,CAAC,UAAU,CAAC;YAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3E,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IACtE,CAAC;IACD,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC;IACtB,IAAI,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;IAC/D,KAAK,MAAM,SAAS,IAAI,CAAC,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,CAAC;QAC9E,IAAI,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;IACtE,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;AACtC,CAAC;AAED,SAAS,UAAU,CAAC,IAAY,EAAE,GAAsB;IACtD,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACnF,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACvC,IAAI,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;IAC9C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/terminal.d.ts

@@ -0,0 +1,42 @@
+export interface TerminalOptions {
+    /** Shell executable. Defaults to the user's shell (see defaultShell). */
+    shell?: string | undefined;
+    /** Arguments for the shell. Defaults depend on the shell chosen. */
+    args?: string[] | undefined;
+    cwd: string;
+    /** Added on top of the host process environment. */
+    env?: Record<string, string> | undefined;
+    cols: number;
+    rows: number;
+    /** Lines kept above the screen for reconnects. Default 5000. */
+    scrollback?: number | undefined;
+}
+export interface TerminalExit {
+    exitCode: number;
+    signal?: number | undefined;
+}
+export interface Terminal {
+    readonly pid: number;
+    readonly cols: number;
+    readonly rows: number;
+    /** Set once the shell has exited. */
+    readonly exit: TerminalExit | null;
+    /** Keyboard input, pasted text, control bytes such as 0x03 for Ctrl+C. */
+    write(data: Uint8Array | string): void;
+    resize(cols: number, rows: number): void;
+    /** Output as the shell wrote it. */
+    onData(listener: (data: Uint8Array) => void): () => void;
+    onExit(listener: (exit: TerminalExit) => void): () => void;
+    /** The current screen and scrollback as bytes a terminal can write after a reset. */
+    snapshot(): Promise<Uint8Array>;
+    /** Stops reading from the shell, so it blocks on its next write. For flow control. */
+    pause(): void;
+    resume(): void;
+    /** Ends the shell. onExit follows. */
+    kill(): void;
+}
+/** Starts a shell in a PTY. Throws PtyUnavailableError when this platform has no PTY binary. */
+export declare function createTerminal(options: TerminalOptions): Terminal;
+/** What the shell inherits: the host's environment plus what a terminal expects. */
+export declare function terminalEnv(extra?: Record<string, string>, base?: NodeJS.ProcessEnv): Record<string, string>;
+//# sourceMappingURL=terminal.d.ts.map

package/dist/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../src/terminal.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC,0EAA0E;IAC1E,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;IACvC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,oCAAoC;IACpC,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACzD,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC3D,qFAAqF;IACrF,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAChC,sFAAsF;IACtF,KAAK,IAAI,IAAI,CAAC;IACd,MAAM,IAAI,IAAI,CAAC;IACf,sCAAsC;IACtC,IAAI,IAAI,IAAI,CAAC;CACd;AAKD,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,QAAQ,CAYjE;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EAAE,IAAI,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAU7H"}

package/dist/terminal.js

@@ -0,0 +1,132 @@
+import { loadPty } from "./pty.js";
+import { Screen } from "./screen.js";
+import { defaultShell } from "./shell.js";
+const DEFAULT_SCROLLBACK = 5000;
+const encoder = new TextEncoder();
+/** Starts a shell in a PTY. Throws PtyUnavailableError when this platform has no PTY binary. */
+export function createTerminal(options) {
+    const pty = loadPty();
+    const shell = options.shell ? { file: options.shell, args: options.args ?? [] } : defaultShell();
+    const args = options.args ?? shell.args;
+    const child = pty.spawn(shell.file, args, {
+        name: "xterm-256color",
+        cols: options.cols,
+        rows: options.rows,
+        cwd: options.cwd,
+        env: terminalEnv(options.env),
+    });
+    return new PtyTerminal(child, options.cols, options.rows, options.scrollback ?? DEFAULT_SCROLLBACK);
+}
+/** What the shell inherits: the host's environment plus what a terminal expects. */
+export function terminalEnv(extra = {}, base = process.env) {
+    const env = {};
+    for (const [key, value] of Object.entries(base))
+        if (value !== undefined)
+            env[key] = value;
+    env.TERM = "xterm-256color";
+    env.COLORTERM = "truecolor";
+    env.TERM_PROGRAM = "termlink";
+    if (process.platform !== "win32" && !env.LANG && !env.LC_ALL && !env.LC_CTYPE) {
+        env.LANG = process.platform === "darwin" ? "en_US.UTF-8" : "C.UTF-8";
+    }
+    return { ...env, ...extra };
+}
+class PtyTerminal {
+    pid;
+    #pty;
+    #screen;
+    #decoder = new TextDecoder("utf-8");
+    #dataListeners = new Set();
+    #exitListeners = new Set();
+    #cols;
+    #rows;
+    #exit = null;
+    constructor(pty, cols, rows, scrollback) {
+        this.#pty = pty;
+        this.pid = pty.pid;
+        this.#cols = cols;
+        this.#rows = rows;
+        this.#screen = new Screen(cols, rows, scrollback);
+        pty.onData((text) => {
+            this.#screen.write(text);
+            const bytes = encoder.encode(text);
+            for (const listener of this.#dataListeners)
+                listener(bytes);
+        });
+        pty.onExit((exit) => {
+            this.#exit = { exitCode: exit.exitCode, signal: exit.signal };
+            // On Windows the ConPTY worker stays referenced after the child exits until the
+            // pty is killed, which would keep the host process alive. Harmless elsewhere.
+            try {
+                pty.kill();
+            }
+            catch {
+                // Already released.
+            }
+            for (const listener of this.#exitListeners)
+                listener(this.#exit);
+            this.#exitListeners.clear();
+            this.#dataListeners.clear();
+            this.#screen.dispose();
+        });
+    }
+    get cols() {
+        return this.#cols;
+    }
+    get rows() {
+        return this.#rows;
+    }
+    get exit() {
+        return this.#exit;
+    }
+    write(data) {
+        if (this.#exit)
+            return;
+        // A multi-byte character split across two frames is joined here.
+        this.#pty.write(typeof data === "string" ? data : this.#decoder.decode(data, { stream: true }));
+    }
+    resize(cols, rows) {
+        if (this.#exit || (cols === this.#cols && rows === this.#rows))
+            return;
+        this.#cols = cols;
+        this.#rows = rows;
+        this.#pty.resize(cols, rows);
+        this.#screen.resize(cols, rows);
+    }
+    onData(listener) {
+        this.#dataListeners.add(listener);
+        return () => this.#dataListeners.delete(listener);
+    }
+    onExit(listener) {
+        if (this.#exit) {
+            listener(this.#exit);
+            return () => { };
+        }
+        this.#exitListeners.add(listener);
+        return () => this.#exitListeners.delete(listener);
+    }
+    async snapshot() {
+        if (this.#exit)
+            return new Uint8Array();
+        return encoder.encode(await this.#screen.snapshot());
+    }
+    pause() {
+        if (!this.#exit)
+            this.#pty.pause();
+    }
+    resume() {
+        if (!this.#exit)
+            this.#pty.resume();
+    }
+    kill() {
+        if (this.#exit)
+            return;
+        try {
+            this.#pty.kill();
+        }
+        catch {
+            // Already gone.
+        }
+    }
+}
+//# sourceMappingURL=terminal.js.map

package/dist/terminal.js.map

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

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@termlink/terminal",
+  "version": "0.1.0",
+  "description": "A shell in a PTY with a headless screen for reconnects. Knows nothing about hosts or clients.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "test": "node --conditions=source --import tsx --test \"test/**/*.test.ts\"",
+    "prepublishOnly": "tsc -b"
+  },
+  "dependencies": {
+    "@xterm/addon-serialize": "^0.14.0",
+    "@xterm/headless": "^6.0.0"
+  },
+  "optionalDependencies": {
+    "@lydell/node-pty": "^1.2.0-beta.15"
+  },
+  "license": "MIT",
+  "author": "Bert Shim",
+  "homepage": "https://getterm.link",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "termlink",
+    "pty",
+    "terminal"
+  ],
+  "engines": {
+    "node": ">=22"
+  }
+}