@slicervm/sdk 0.1.5 → 0.1.6

package/dist/shell.cjs

@@ -0,0 +1,152 @@
+'use strict';
+
+// src/shell.ts
+var FRAME_TYPE_DATA = 1;
+var FRAME_TYPE_WINDOW_SIZE = 2;
+var FRAME_TYPE_SHUTDOWN = 3;
+var FRAME_TYPE_HEARTBEAT = 4;
+var FRAME_TYPE_SESSION_CLOSE = 5;
+var HEADER_SIZE = 5;
+function encodeFrame(frameType, payload) {
+  const payloadLen = payload ? payload.byteLength : 0;
+  const buf = new Uint8Array(HEADER_SIZE + payloadLen);
+  const view = new DataView(buf.buffer);
+  view.setUint8(0, frameType);
+  view.setUint32(1, payloadLen, false);
+  if (payload) buf.set(payload, HEADER_SIZE);
+  return buf;
+}
+function parseFrame(data) {
+  if (data.byteLength < HEADER_SIZE) return null;
+  const view = new DataView(data);
+  const frameType = view.getUint8(0);
+  const payloadLen = view.getUint32(1, false);
+  if (data.byteLength < HEADER_SIZE + payloadLen) return null;
+  const payload = new Uint8Array(data, HEADER_SIZE, payloadLen);
+  return { frameType, payload };
+}
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+var SlicerShellSession = class {
+  constructor(terminal, options) {
+    this.terminal = terminal;
+    this.options = options;
+  }
+  terminal;
+  options;
+  ws = null;
+  heartbeatTimer = null;
+  dataDisposable = null;
+  /** True when the WebSocket is open and relaying. */
+  get connected() {
+    return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+  }
+  /** Open the WebSocket and begin relaying. */
+  connect() {
+    if (this.ws) return;
+    this.options.onStateChange?.("connecting");
+    const ws = new WebSocket(this.options.url);
+    ws.binaryType = "arraybuffer";
+    this.ws = ws;
+    ws.onopen = () => {
+      this.options.onStateChange?.("connected");
+      this.terminal.reset();
+      this.sendResize(this.terminal.cols, this.terminal.rows);
+      this.startHeartbeat();
+    };
+    ws.onmessage = (ev) => {
+      if (!(ev.data instanceof ArrayBuffer)) return;
+      const frame = parseFrame(ev.data);
+      if (!frame) return;
+      switch (frame.frameType) {
+        case FRAME_TYPE_DATA:
+          this.terminal.write(decoder.decode(frame.payload));
+          break;
+        case FRAME_TYPE_SHUTDOWN:
+        case FRAME_TYPE_SESSION_CLOSE:
+          this.teardown();
+          break;
+      }
+    };
+    ws.onclose = () => {
+      this.teardown();
+    };
+    ws.onerror = () => {
+      this.options.onError?.("WebSocket error");
+      this.teardown();
+    };
+    this.dataDisposable = this.terminal.onData((data) => {
+      if (!this.connected) return;
+      const payload = encoder.encode(data);
+      this.ws.send(encodeFrame(FRAME_TYPE_DATA, payload));
+    });
+  }
+  /** Send a graceful shutdown frame and close. */
+  disconnect() {
+    if (this.ws) {
+      try {
+        this.ws.send(encodeFrame(FRAME_TYPE_SHUTDOWN));
+      } catch {
+      }
+    }
+    this.teardown();
+  }
+  /** Send a window resize. Call this from FitAddon's onResize or a ResizeObserver. */
+  resize(cols, rows) {
+    if (!this.connected) return;
+    this.sendResize(cols, rows);
+  }
+  // --- internals -------------------------------------------------------------
+  sendResize(cols, rows) {
+    const payload = new Uint8Array(8);
+    const view = new DataView(payload.buffer);
+    view.setUint32(0, cols, false);
+    view.setUint32(4, rows, false);
+    this.ws.send(encodeFrame(FRAME_TYPE_WINDOW_SIZE, payload));
+  }
+  startHeartbeat() {
+    this.stopHeartbeat();
+    const intervalMs = this.options.heartbeatIntervalMs ?? 3e4;
+    this.heartbeatTimer = setInterval(() => {
+      if (!this.connected) return;
+      this.ws.send(encodeFrame(FRAME_TYPE_HEARTBEAT));
+    }, intervalMs);
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer !== null) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+  teardown() {
+    this.stopHeartbeat();
+    if (this.dataDisposable) {
+      this.dataDisposable.dispose();
+      this.dataDisposable = null;
+    }
+    if (this.ws) {
+      const ws = this.ws;
+      this.ws = null;
+      ws.onopen = null;
+      ws.onmessage = null;
+      ws.onclose = null;
+      ws.onerror = null;
+      try {
+        ws.close();
+      } catch {
+      }
+    }
+    this.options.onStateChange?.("disconnected");
+  }
+};
+
+exports.FRAME_TYPE_DATA = FRAME_TYPE_DATA;
+exports.FRAME_TYPE_HEARTBEAT = FRAME_TYPE_HEARTBEAT;
+exports.FRAME_TYPE_SESSION_CLOSE = FRAME_TYPE_SESSION_CLOSE;
+exports.FRAME_TYPE_SHUTDOWN = FRAME_TYPE_SHUTDOWN;
+exports.FRAME_TYPE_WINDOW_SIZE = FRAME_TYPE_WINDOW_SIZE;
+exports.SlicerShellSession = SlicerShellSession;
+exports.encodeFrame = encodeFrame;
+exports.parseFrame = parseFrame;
+//# sourceMappingURL=shell.cjs.map
+//# sourceMappingURL=shell.cjs.map

package/dist/shell.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/shell.ts"],"names":[],"mappings":"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","file":"shell.cjs","sourcesContent":["/**\n * Browser-compatible shell adapter for Slicer VMs.\n *\n * Provides frame encode/decode helpers and a `SlicerShellSession` class that\n * wires a standard browser WebSocket to an xterm.js Terminal instance using\n * the Slicer binary shell protocol.\n *\n * This module intentionally avoids Node-only imports so it can be used in\n * browser bundles.\n */\n\n// --- frame type constants ----------------------------------------------------\n\nexport const FRAME_TYPE_DATA = 0x01;\nexport const FRAME_TYPE_WINDOW_SIZE = 0x02;\nexport const FRAME_TYPE_SHUTDOWN = 0x03;\nexport const FRAME_TYPE_HEARTBEAT = 0x04;\nexport const FRAME_TYPE_SESSION_CLOSE = 0x05;\n\n// --- frame helpers -----------------------------------------------------------\n\nconst HEADER_SIZE = 5;\n\n/** Encode a frame into the 5-byte-header binary protocol. */\nexport function encodeFrame(frameType: number, payload?: Uint8Array): Uint8Array {\n  const payloadLen = payload ? payload.byteLength : 0;\n  const buf = new Uint8Array(HEADER_SIZE + payloadLen);\n  const view = new DataView(buf.buffer);\n  view.setUint8(0, frameType);\n  view.setUint32(1, payloadLen, false); // big-endian\n  if (payload) buf.set(payload, HEADER_SIZE);\n  return buf;\n}\n\n/** Parse a binary frame. Returns null if the data is malformed. */\nexport function parseFrame(data: ArrayBuffer): { frameType: number; payload: Uint8Array } | null {\n  if (data.byteLength < HEADER_SIZE) return null;\n  const view = new DataView(data);\n  const frameType = view.getUint8(0);\n  const payloadLen = view.getUint32(1, false); // big-endian\n  if (data.byteLength < HEADER_SIZE + payloadLen) return null;\n  const payload = new Uint8Array(data, HEADER_SIZE, payloadLen);\n  return { frameType, payload };\n}\n\n// --- types -------------------------------------------------------------------\n\nexport interface ShellSessionOptions {\n  /** WebSocket URL for the shell endpoint (ws:// or wss://). */\n  url: string;\n  /** Heartbeat interval in ms. Default 30000. */\n  heartbeatIntervalMs?: number;\n  /** Called when connection state changes. */\n  onStateChange?: (state: 'connecting' | 'connected' | 'disconnected') => void;\n  /** Called on error. */\n  onError?: (error: string) => void;\n}\n\n/**\n * Minimal xterm.js Terminal interface — only the methods SlicerShellSession\n * actually calls. Avoids requiring @xterm/xterm as a dependency.\n */\nexport interface XTermLike {\n  onData: (cb: (data: string) => void) => { dispose: () => void };\n  write: (data: string) => void;\n  reset: () => void;\n  cols: number;\n  rows: number;\n}\n\n// --- minimal browser type stubs ----------------------------------------------\n// The SDK targets Node (lib: ES2022, no DOM). Declare the subset of browser\n// APIs the class actually uses so this file compiles without adding \"DOM\" to\n// the project-wide tsconfig.\n\ninterface BrowserWebSocket {\n  binaryType: string;\n  readyState: number;\n  onopen: ((ev: unknown) => void) | null;\n  onmessage: ((ev: { data: unknown }) => void) | null;\n  onclose: ((ev: unknown) => void) | null;\n  onerror: ((ev: unknown) => void) | null;\n  send(data: ArrayBufferLike | Uint8Array | string): void;\n  close(code?: number, reason?: string): void;\n}\n\ninterface BrowserWebSocketConstructor {\n  new (url: string): BrowserWebSocket;\n  readonly OPEN: number;\n}\n\ndeclare const WebSocket: BrowserWebSocketConstructor;\n\n// --- class -------------------------------------------------------------------\n\nconst encoder = new TextEncoder();\nconst decoder = new TextDecoder();\n\nexport class SlicerShellSession {\n  private ws: BrowserWebSocket | null = null;\n  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;\n  private dataDisposable: { dispose: () => void } | null = null;\n\n  constructor(\n    private readonly terminal: XTermLike,\n    private readonly options: ShellSessionOptions,\n  ) {}\n\n  /** True when the WebSocket is open and relaying. */\n  get connected(): boolean {\n    return this.ws !== null && this.ws.readyState === WebSocket.OPEN;\n  }\n\n  /** Open the WebSocket and begin relaying. */\n  connect(): void {\n    if (this.ws) return;\n    this.options.onStateChange?.('connecting');\n\n    const ws = new WebSocket(this.options.url);\n    ws.binaryType = 'arraybuffer';\n    this.ws = ws;\n\n    ws.onopen = () => {\n      this.options.onStateChange?.('connected');\n      this.terminal.reset();\n      this.sendResize(this.terminal.cols, this.terminal.rows);\n      this.startHeartbeat();\n    };\n\n    ws.onmessage = (ev: { data: unknown }) => {\n      if (!(ev.data instanceof ArrayBuffer)) return;\n      const frame = parseFrame(ev.data);\n      if (!frame) return;\n\n      switch (frame.frameType) {\n        case FRAME_TYPE_DATA:\n          this.terminal.write(decoder.decode(frame.payload));\n          break;\n        case FRAME_TYPE_SHUTDOWN:\n        case FRAME_TYPE_SESSION_CLOSE:\n          this.teardown();\n          break;\n      }\n    };\n\n    ws.onclose = () => {\n      this.teardown();\n    };\n\n    ws.onerror = () => {\n      this.options.onError?.('WebSocket error');\n      this.teardown();\n    };\n\n    this.dataDisposable = this.terminal.onData((data: string) => {\n      if (!this.connected) return;\n      const payload = encoder.encode(data);\n      this.ws!.send(encodeFrame(FRAME_TYPE_DATA, payload));\n    });\n  }\n\n  /** Send a graceful shutdown frame and close. */\n  disconnect(): void {\n    if (this.ws) {\n      try {\n        this.ws.send(encodeFrame(FRAME_TYPE_SHUTDOWN));\n      } catch {\n        /* ws may already be closed */\n      }\n    }\n    this.teardown();\n  }\n\n  /** Send a window resize. Call this from FitAddon's onResize or a ResizeObserver. */\n  resize(cols: number, rows: number): void {\n    if (!this.connected) return;\n    this.sendResize(cols, rows);\n  }\n\n  // --- internals -------------------------------------------------------------\n\n  private sendResize(cols: number, rows: number): void {\n    const payload = new Uint8Array(8);\n    const view = new DataView(payload.buffer);\n    view.setUint32(0, cols, false); // big-endian\n    view.setUint32(4, rows, false);\n    this.ws!.send(encodeFrame(FRAME_TYPE_WINDOW_SIZE, payload));\n  }\n\n  private startHeartbeat(): void {\n    this.stopHeartbeat();\n    const intervalMs = this.options.heartbeatIntervalMs ?? 30_000;\n    this.heartbeatTimer = setInterval(() => {\n      if (!this.connected) return;\n      this.ws!.send(encodeFrame(FRAME_TYPE_HEARTBEAT));\n    }, intervalMs);\n  }\n\n  private stopHeartbeat(): void {\n    if (this.heartbeatTimer !== null) {\n      clearInterval(this.heartbeatTimer);\n      this.heartbeatTimer = null;\n    }\n  }\n\n  private teardown(): void {\n    this.stopHeartbeat();\n    if (this.dataDisposable) {\n      this.dataDisposable.dispose();\n      this.dataDisposable = null;\n    }\n    if (this.ws) {\n      const ws = this.ws;\n      this.ws = null;\n      ws.onopen = null;\n      ws.onmessage = null;\n      ws.onclose = null;\n      ws.onerror = null;\n      try {\n        ws.close();\n      } catch {\n        /* ignore */\n      }\n    }\n    this.options.onStateChange?.('disconnected');\n  }\n}\n"]}

package/dist/shell.d.cts

@@ -0,0 +1,67 @@
+/**
+ * Browser-compatible shell adapter for Slicer VMs.
+ *
+ * Provides frame encode/decode helpers and a `SlicerShellSession` class that
+ * wires a standard browser WebSocket to an xterm.js Terminal instance using
+ * the Slicer binary shell protocol.
+ *
+ * This module intentionally avoids Node-only imports so it can be used in
+ * browser bundles.
+ */
+declare const FRAME_TYPE_DATA = 1;
+declare const FRAME_TYPE_WINDOW_SIZE = 2;
+declare const FRAME_TYPE_SHUTDOWN = 3;
+declare const FRAME_TYPE_HEARTBEAT = 4;
+declare const FRAME_TYPE_SESSION_CLOSE = 5;
+/** Encode a frame into the 5-byte-header binary protocol. */
+declare function encodeFrame(frameType: number, payload?: Uint8Array): Uint8Array;
+/** Parse a binary frame. Returns null if the data is malformed. */
+declare function parseFrame(data: ArrayBuffer): {
+    frameType: number;
+    payload: Uint8Array;
+} | null;
+interface ShellSessionOptions {
+    /** WebSocket URL for the shell endpoint (ws:// or wss://). */
+    url: string;
+    /** Heartbeat interval in ms. Default 30000. */
+    heartbeatIntervalMs?: number;
+    /** Called when connection state changes. */
+    onStateChange?: (state: 'connecting' | 'connected' | 'disconnected') => void;
+    /** Called on error. */
+    onError?: (error: string) => void;
+}
+/**
+ * Minimal xterm.js Terminal interface — only the methods SlicerShellSession
+ * actually calls. Avoids requiring @xterm/xterm as a dependency.
+ */
+interface XTermLike {
+    onData: (cb: (data: string) => void) => {
+        dispose: () => void;
+    };
+    write: (data: string) => void;
+    reset: () => void;
+    cols: number;
+    rows: number;
+}
+declare class SlicerShellSession {
+    private readonly terminal;
+    private readonly options;
+    private ws;
+    private heartbeatTimer;
+    private dataDisposable;
+    constructor(terminal: XTermLike, options: ShellSessionOptions);
+    /** True when the WebSocket is open and relaying. */
+    get connected(): boolean;
+    /** Open the WebSocket and begin relaying. */
+    connect(): void;
+    /** Send a graceful shutdown frame and close. */
+    disconnect(): void;
+    /** Send a window resize. Call this from FitAddon's onResize or a ResizeObserver. */
+    resize(cols: number, rows: number): void;
+    private sendResize;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private teardown;
+}
+
+export { FRAME_TYPE_DATA, FRAME_TYPE_HEARTBEAT, FRAME_TYPE_SESSION_CLOSE, FRAME_TYPE_SHUTDOWN, FRAME_TYPE_WINDOW_SIZE, type ShellSessionOptions, SlicerShellSession, type XTermLike, encodeFrame, parseFrame };

package/dist/shell.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Browser-compatible shell adapter for Slicer VMs.
+ *
+ * Provides frame encode/decode helpers and a `SlicerShellSession` class that
+ * wires a standard browser WebSocket to an xterm.js Terminal instance using
+ * the Slicer binary shell protocol.
+ *
+ * This module intentionally avoids Node-only imports so it can be used in
+ * browser bundles.
+ */
+declare const FRAME_TYPE_DATA = 1;
+declare const FRAME_TYPE_WINDOW_SIZE = 2;
+declare const FRAME_TYPE_SHUTDOWN = 3;
+declare const FRAME_TYPE_HEARTBEAT = 4;
+declare const FRAME_TYPE_SESSION_CLOSE = 5;
+/** Encode a frame into the 5-byte-header binary protocol. */
+declare function encodeFrame(frameType: number, payload?: Uint8Array): Uint8Array;
+/** Parse a binary frame. Returns null if the data is malformed. */
+declare function parseFrame(data: ArrayBuffer): {
+    frameType: number;
+    payload: Uint8Array;
+} | null;
+interface ShellSessionOptions {
+    /** WebSocket URL for the shell endpoint (ws:// or wss://). */
+    url: string;
+    /** Heartbeat interval in ms. Default 30000. */
+    heartbeatIntervalMs?: number;
+    /** Called when connection state changes. */
+    onStateChange?: (state: 'connecting' | 'connected' | 'disconnected') => void;
+    /** Called on error. */
+    onError?: (error: string) => void;
+}
+/**
+ * Minimal xterm.js Terminal interface — only the methods SlicerShellSession
+ * actually calls. Avoids requiring @xterm/xterm as a dependency.
+ */
+interface XTermLike {
+    onData: (cb: (data: string) => void) => {
+        dispose: () => void;
+    };
+    write: (data: string) => void;
+    reset: () => void;
+    cols: number;
+    rows: number;
+}
+declare class SlicerShellSession {
+    private readonly terminal;
+    private readonly options;
+    private ws;
+    private heartbeatTimer;
+    private dataDisposable;
+    constructor(terminal: XTermLike, options: ShellSessionOptions);
+    /** True when the WebSocket is open and relaying. */
+    get connected(): boolean;
+    /** Open the WebSocket and begin relaying. */
+    connect(): void;
+    /** Send a graceful shutdown frame and close. */
+    disconnect(): void;
+    /** Send a window resize. Call this from FitAddon's onResize or a ResizeObserver. */
+    resize(cols: number, rows: number): void;
+    private sendResize;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private teardown;
+}
+
+export { FRAME_TYPE_DATA, FRAME_TYPE_HEARTBEAT, FRAME_TYPE_SESSION_CLOSE, FRAME_TYPE_SHUTDOWN, FRAME_TYPE_WINDOW_SIZE, type ShellSessionOptions, SlicerShellSession, type XTermLike, encodeFrame, parseFrame };

package/dist/shell.js

@@ -0,0 +1,143 @@
+// src/shell.ts
+var FRAME_TYPE_DATA = 1;
+var FRAME_TYPE_WINDOW_SIZE = 2;
+var FRAME_TYPE_SHUTDOWN = 3;
+var FRAME_TYPE_HEARTBEAT = 4;
+var FRAME_TYPE_SESSION_CLOSE = 5;
+var HEADER_SIZE = 5;
+function encodeFrame(frameType, payload) {
+  const payloadLen = payload ? payload.byteLength : 0;
+  const buf = new Uint8Array(HEADER_SIZE + payloadLen);
+  const view = new DataView(buf.buffer);
+  view.setUint8(0, frameType);
+  view.setUint32(1, payloadLen, false);
+  if (payload) buf.set(payload, HEADER_SIZE);
+  return buf;
+}
+function parseFrame(data) {
+  if (data.byteLength < HEADER_SIZE) return null;
+  const view = new DataView(data);
+  const frameType = view.getUint8(0);
+  const payloadLen = view.getUint32(1, false);
+  if (data.byteLength < HEADER_SIZE + payloadLen) return null;
+  const payload = new Uint8Array(data, HEADER_SIZE, payloadLen);
+  return { frameType, payload };
+}
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+var SlicerShellSession = class {
+  constructor(terminal, options) {
+    this.terminal = terminal;
+    this.options = options;
+  }
+  terminal;
+  options;
+  ws = null;
+  heartbeatTimer = null;
+  dataDisposable = null;
+  /** True when the WebSocket is open and relaying. */
+  get connected() {
+    return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+  }
+  /** Open the WebSocket and begin relaying. */
+  connect() {
+    if (this.ws) return;
+    this.options.onStateChange?.("connecting");
+    const ws = new WebSocket(this.options.url);
+    ws.binaryType = "arraybuffer";
+    this.ws = ws;
+    ws.onopen = () => {
+      this.options.onStateChange?.("connected");
+      this.terminal.reset();
+      this.sendResize(this.terminal.cols, this.terminal.rows);
+      this.startHeartbeat();
+    };
+    ws.onmessage = (ev) => {
+      if (!(ev.data instanceof ArrayBuffer)) return;
+      const frame = parseFrame(ev.data);
+      if (!frame) return;
+      switch (frame.frameType) {
+        case FRAME_TYPE_DATA:
+          this.terminal.write(decoder.decode(frame.payload));
+          break;
+        case FRAME_TYPE_SHUTDOWN:
+        case FRAME_TYPE_SESSION_CLOSE:
+          this.teardown();
+          break;
+      }
+    };
+    ws.onclose = () => {
+      this.teardown();
+    };
+    ws.onerror = () => {
+      this.options.onError?.("WebSocket error");
+      this.teardown();
+    };
+    this.dataDisposable = this.terminal.onData((data) => {
+      if (!this.connected) return;
+      const payload = encoder.encode(data);
+      this.ws.send(encodeFrame(FRAME_TYPE_DATA, payload));
+    });
+  }
+  /** Send a graceful shutdown frame and close. */
+  disconnect() {
+    if (this.ws) {
+      try {
+        this.ws.send(encodeFrame(FRAME_TYPE_SHUTDOWN));
+      } catch {
+      }
+    }
+    this.teardown();
+  }
+  /** Send a window resize. Call this from FitAddon's onResize or a ResizeObserver. */
+  resize(cols, rows) {
+    if (!this.connected) return;
+    this.sendResize(cols, rows);
+  }
+  // --- internals -------------------------------------------------------------
+  sendResize(cols, rows) {
+    const payload = new Uint8Array(8);
+    const view = new DataView(payload.buffer);
+    view.setUint32(0, cols, false);
+    view.setUint32(4, rows, false);
+    this.ws.send(encodeFrame(FRAME_TYPE_WINDOW_SIZE, payload));
+  }
+  startHeartbeat() {
+    this.stopHeartbeat();
+    const intervalMs = this.options.heartbeatIntervalMs ?? 3e4;
+    this.heartbeatTimer = setInterval(() => {
+      if (!this.connected) return;
+      this.ws.send(encodeFrame(FRAME_TYPE_HEARTBEAT));
+    }, intervalMs);
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer !== null) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+  teardown() {
+    this.stopHeartbeat();
+    if (this.dataDisposable) {
+      this.dataDisposable.dispose();
+      this.dataDisposable = null;
+    }
+    if (this.ws) {
+      const ws = this.ws;
+      this.ws = null;
+      ws.onopen = null;
+      ws.onmessage = null;
+      ws.onclose = null;
+      ws.onerror = null;
+      try {
+        ws.close();
+      } catch {
+      }
+    }
+    this.options.onStateChange?.("disconnected");
+  }
+};
+
+export { FRAME_TYPE_DATA, FRAME_TYPE_HEARTBEAT, FRAME_TYPE_SESSION_CLOSE, FRAME_TYPE_SHUTDOWN, FRAME_TYPE_WINDOW_SIZE, SlicerShellSession, encodeFrame, parseFrame };
+//# sourceMappingURL=shell.js.map
+//# sourceMappingURL=shell.js.map

package/dist/shell.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/shell.ts"],"names":[],"mappings":"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","file":"shell.js","sourcesContent":["/**\n * Browser-compatible shell adapter for Slicer VMs.\n *\n * Provides frame encode/decode helpers and a `SlicerShellSession` class that\n * wires a standard browser WebSocket to an xterm.js Terminal instance using\n * the Slicer binary shell protocol.\n *\n * This module intentionally avoids Node-only imports so it can be used in\n * browser bundles.\n */\n\n// --- frame type constants ----------------------------------------------------\n\nexport const FRAME_TYPE_DATA = 0x01;\nexport const FRAME_TYPE_WINDOW_SIZE = 0x02;\nexport const FRAME_TYPE_SHUTDOWN = 0x03;\nexport const FRAME_TYPE_HEARTBEAT = 0x04;\nexport const FRAME_TYPE_SESSION_CLOSE = 0x05;\n\n// --- frame helpers -----------------------------------------------------------\n\nconst HEADER_SIZE = 5;\n\n/** Encode a frame into the 5-byte-header binary protocol. */\nexport function encodeFrame(frameType: number, payload?: Uint8Array): Uint8Array {\n  const payloadLen = payload ? payload.byteLength : 0;\n  const buf = new Uint8Array(HEADER_SIZE + payloadLen);\n  const view = new DataView(buf.buffer);\n  view.setUint8(0, frameType);\n  view.setUint32(1, payloadLen, false); // big-endian\n  if (payload) buf.set(payload, HEADER_SIZE);\n  return buf;\n}\n\n/** Parse a binary frame. Returns null if the data is malformed. */\nexport function parseFrame(data: ArrayBuffer): { frameType: number; payload: Uint8Array } | null {\n  if (data.byteLength < HEADER_SIZE) return null;\n  const view = new DataView(data);\n  const frameType = view.getUint8(0);\n  const payloadLen = view.getUint32(1, false); // big-endian\n  if (data.byteLength < HEADER_SIZE + payloadLen) return null;\n  const payload = new Uint8Array(data, HEADER_SIZE, payloadLen);\n  return { frameType, payload };\n}\n\n// --- types -------------------------------------------------------------------\n\nexport interface ShellSessionOptions {\n  /** WebSocket URL for the shell endpoint (ws:// or wss://). */\n  url: string;\n  /** Heartbeat interval in ms. Default 30000. */\n  heartbeatIntervalMs?: number;\n  /** Called when connection state changes. */\n  onStateChange?: (state: 'connecting' | 'connected' | 'disconnected') => void;\n  /** Called on error. */\n  onError?: (error: string) => void;\n}\n\n/**\n * Minimal xterm.js Terminal interface — only the methods SlicerShellSession\n * actually calls. Avoids requiring @xterm/xterm as a dependency.\n */\nexport interface XTermLike {\n  onData: (cb: (data: string) => void) => { dispose: () => void };\n  write: (data: string) => void;\n  reset: () => void;\n  cols: number;\n  rows: number;\n}\n\n// --- minimal browser type stubs ----------------------------------------------\n// The SDK targets Node (lib: ES2022, no DOM). Declare the subset of browser\n// APIs the class actually uses so this file compiles without adding \"DOM\" to\n// the project-wide tsconfig.\n\ninterface BrowserWebSocket {\n  binaryType: string;\n  readyState: number;\n  onopen: ((ev: unknown) => void) | null;\n  onmessage: ((ev: { data: unknown }) => void) | null;\n  onclose: ((ev: unknown) => void) | null;\n  onerror: ((ev: unknown) => void) | null;\n  send(data: ArrayBufferLike | Uint8Array | string): void;\n  close(code?: number, reason?: string): void;\n}\n\ninterface BrowserWebSocketConstructor {\n  new (url: string): BrowserWebSocket;\n  readonly OPEN: number;\n}\n\ndeclare const WebSocket: BrowserWebSocketConstructor;\n\n// --- class -------------------------------------------------------------------\n\nconst encoder = new TextEncoder();\nconst decoder = new TextDecoder();\n\nexport class SlicerShellSession {\n  private ws: BrowserWebSocket | null = null;\n  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;\n  private dataDisposable: { dispose: () => void } | null = null;\n\n  constructor(\n    private readonly terminal: XTermLike,\n    private readonly options: ShellSessionOptions,\n  ) {}\n\n  /** True when the WebSocket is open and relaying. */\n  get connected(): boolean {\n    return this.ws !== null && this.ws.readyState === WebSocket.OPEN;\n  }\n\n  /** Open the WebSocket and begin relaying. */\n  connect(): void {\n    if (this.ws) return;\n    this.options.onStateChange?.('connecting');\n\n    const ws = new WebSocket(this.options.url);\n    ws.binaryType = 'arraybuffer';\n    this.ws = ws;\n\n    ws.onopen = () => {\n      this.options.onStateChange?.('connected');\n      this.terminal.reset();\n      this.sendResize(this.terminal.cols, this.terminal.rows);\n      this.startHeartbeat();\n    };\n\n    ws.onmessage = (ev: { data: unknown }) => {\n      if (!(ev.data instanceof ArrayBuffer)) return;\n      const frame = parseFrame(ev.data);\n      if (!frame) return;\n\n      switch (frame.frameType) {\n        case FRAME_TYPE_DATA:\n          this.terminal.write(decoder.decode(frame.payload));\n          break;\n        case FRAME_TYPE_SHUTDOWN:\n        case FRAME_TYPE_SESSION_CLOSE:\n          this.teardown();\n          break;\n      }\n    };\n\n    ws.onclose = () => {\n      this.teardown();\n    };\n\n    ws.onerror = () => {\n      this.options.onError?.('WebSocket error');\n      this.teardown();\n    };\n\n    this.dataDisposable = this.terminal.onData((data: string) => {\n      if (!this.connected) return;\n      const payload = encoder.encode(data);\n      this.ws!.send(encodeFrame(FRAME_TYPE_DATA, payload));\n    });\n  }\n\n  /** Send a graceful shutdown frame and close. */\n  disconnect(): void {\n    if (this.ws) {\n      try {\n        this.ws.send(encodeFrame(FRAME_TYPE_SHUTDOWN));\n      } catch {\n        /* ws may already be closed */\n      }\n    }\n    this.teardown();\n  }\n\n  /** Send a window resize. Call this from FitAddon's onResize or a ResizeObserver. */\n  resize(cols: number, rows: number): void {\n    if (!this.connected) return;\n    this.sendResize(cols, rows);\n  }\n\n  // --- internals -------------------------------------------------------------\n\n  private sendResize(cols: number, rows: number): void {\n    const payload = new Uint8Array(8);\n    const view = new DataView(payload.buffer);\n    view.setUint32(0, cols, false); // big-endian\n    view.setUint32(4, rows, false);\n    this.ws!.send(encodeFrame(FRAME_TYPE_WINDOW_SIZE, payload));\n  }\n\n  private startHeartbeat(): void {\n    this.stopHeartbeat();\n    const intervalMs = this.options.heartbeatIntervalMs ?? 30_000;\n    this.heartbeatTimer = setInterval(() => {\n      if (!this.connected) return;\n      this.ws!.send(encodeFrame(FRAME_TYPE_HEARTBEAT));\n    }, intervalMs);\n  }\n\n  private stopHeartbeat(): void {\n    if (this.heartbeatTimer !== null) {\n      clearInterval(this.heartbeatTimer);\n      this.heartbeatTimer = null;\n    }\n  }\n\n  private teardown(): void {\n    this.stopHeartbeat();\n    if (this.dataDisposable) {\n      this.dataDisposable.dispose();\n      this.dataDisposable = null;\n    }\n    if (this.ws) {\n      const ws = this.ws;\n      this.ws = null;\n      ws.onopen = null;\n      ws.onmessage = null;\n      ws.onclose = null;\n      ws.onerror = null;\n      try {\n        ws.close();\n      } catch {\n        /* ignore */\n      }\n    }\n    this.options.onStateChange?.('disconnected');\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slicervm/sdk",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "TypeScript SDK for the Slicer VM control-plane API.",
   "license": "MIT",
   "author": "Alex Ellis <alex@openfaas.com>",
@@ -38,6 +38,16 @@
         "types": "./dist/index.d.cts",
         "default": "./dist/index.cjs"
       }
+    },
+    "./shell": {
+      "import": {
+        "types": "./dist/shell.d.ts",
+        "default": "./dist/shell.js"
+      },
+      "require": {
+        "types": "./dist/shell.d.cts",
+        "default": "./dist/shell.cjs"
+      }
     }
   },
   "files": [