@cplieger/web-terminal-engine 2.5.0 → 2.8.0

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "2.5.0",
+  "version": "2.8.0",
   "exports": {
     ".": "./src/index.ts"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-engine",
-  "version": "2.5.0",
+  "version": "2.8.0",
   "type": "module",
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",
@@ -24,7 +24,7 @@
     "pngjs": "7.0.0",
     "prettier": "3.9.5",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.63.0",
+    "typescript-eslint": "8.64.0",
     "vitest": "4.1.10"
   },
   "description": "Browser terminal engine: VT500 screen buffer, DOM renderer, and binary wire protocol",

package/src/connection.ts

@@ -22,6 +22,7 @@
 // without bound.
 
 import { wsURL } from "./wsurl.js";
+import { WS_PATH } from "./routes.js";
 import { controlFrame } from "./wire.js";
 import { decodeWireBinary, WIRE_PROTOCOL_VERSION } from "./wire-binary.js";
 import * as modes from "./modes.js";
@@ -45,7 +46,7 @@ let connState: ConnState = { status: "disconnected" };
 let reconnectDelay = INITIAL_DELAY_MS;
 let lastSentCols = 0;
 let lastSentRows = 0;
-let wsPath = "/ws";
+let wsPath: string = WS_PATH;
 
 // --- Per-session resume state (the switching cache's connection half) ---
 //

package/src/index.ts

@@ -10,8 +10,10 @@ export * as connection from "./connection.js";
 export { decodeWireBinary } from "./wire-binary.js";
 export { controlFrame, CONTROL_FRAME_PREFIX } from "./wire.js";
 export { wsURL } from "./wsurl.js";
+export { WS_PATH, SESSIONS_PATH, SESSION_EVENTS_PATH } from "./routes.js";
 export { connectStatusStream } from "./status-stream.js";
 export type {
+  SessionInfo,
   SessionStatus,
   StatusStream,
   StatusStreamCallbacks,

package/src/routes.ts

@@ -0,0 +1,19 @@
+// Session-route path contract, TS half. These mirror the Go terminal
+// package's exported constants (WSPath, SessionsPath, SessionEventsPath),
+// whose MountSessionRoutes wires exactly this topology on the server — one
+// name per path on each side of the wire, so a consumer composing its own
+// URLs (or overriding a default) references the contract instead of
+// restating a literal that could drift. Any addition here is an addition to
+// the server mount contract and is release-noted on both halves.
+
+/** WS_PATH is the terminal WebSocket route; the client connects per session
+ *  with `?session=<id>`. Mirrors Go `terminal.WSPath`. */
+export const WS_PATH = "/ws";
+
+/** SESSIONS_PATH is the session REST route (POST create, GET list; DELETE and
+ *  PUT title live under its subtree). Mirrors Go `terminal.SessionsPath`. */
+export const SESSIONS_PATH = "/api/sessions";
+
+/** SESSION_EVENTS_PATH is the session status stream (SSE). Mirrors Go
+ *  `terminal.SessionEventsPath`. */
+export const SESSION_EVENTS_PATH = "/api/sessions/events";

package/src/status-stream.ts

@@ -7,9 +7,11 @@
 
 import { nextBackoffDelay } from "./reconnect.js";
 
-/** SessionStatus is one session's current status as carried on the stream. It
- *  mirrors the server's status event. */
-export interface SessionStatus {
+/** SessionInfo is one session's wire shape: the JSON object the session REST
+ *  API (GET/POST /api/sessions) returns per session. Mirrors the Go
+ *  terminal.SessionInfo — the two are kept in lockstep by hand (single 6-field
+ *  type; flip to wiregen if this surface grows). */
+export interface SessionInfo {
   readonly id: string;
   readonly status: "working" | "idle" | "input" | "done" | "exited";
   readonly title: string;
@@ -18,8 +20,6 @@ export interface SessionStatus {
    *  this instead of `title`. */
   readonly clientTitle?: string;
   readonly createdAt: string;
-  /** true when the session is gone (closed or reaped); the consumer drops it. */
-  readonly removed?: boolean;
   /** true once the session has emitted a genuine activity signal — OSC 9;4
    *  progress (kiro-cli, Claude Code, …) or a classified OSC 9 notification.
    *  Sticky for the session's life. Consumers reveal the per-tab activity dot
@@ -28,6 +28,14 @@ export interface SessionStatus {
   readonly reportsActivity?: boolean;
 }
 
+/** SessionStatus is one session's current status as carried on the status
+ *  stream (SSE): the REST wire shape plus the stream-only removal marker. It
+ *  mirrors the server's status event. */
+export interface SessionStatus extends SessionInfo {
+  /** true when the session is gone (closed or reaped); the consumer drops it. */
+  readonly removed?: boolean;
+}
+
 /** StatusStreamCallbacks are the consumer's hooks. Declared as function-typed
  *  properties (not method shorthand) so destructuring them is safe. */
 export interface StatusStreamCallbacks {

package/src/wsurl.ts

@@ -1,3 +1,5 @@
+import { WS_PATH } from "./routes.js";
+
 // Pure URL helper, no DOM / terminal / WebSocket dependencies.
 // Kept in a dedicated module so it can be property-tested without
 // touching `location`. The caller threads the live `location.*` through.
@@ -9,10 +11,10 @@
  *
  * @param pageProtocol `location.protocol` (e.g. `"https:"`).
  * @param pageHost     `location.host` (host[:port]).
- * @param path         WebSocket endpoint path; defaults to `"/ws"`.
+ * @param path         WebSocket endpoint path; defaults to `WS_PATH` (`"/ws"`).
  * @returns            A parseable `ws://`/`wss://` URL.
  */
-export function wsURL(pageProtocol: string, pageHost: string, path = "/ws"): string {
+export function wsURL(pageProtocol: string, pageHost: string, path = WS_PATH): string {
   const wsProto = pageProtocol === "https:" ? "wss:" : "ws:";
   const normalizedPath = path.startsWith("/") ? path : `/${path}`;
   return `${wsProto}//${pageHost}${normalizedPath}`;