@devolutions/web-recorder 0.1.0

package/asciicast-v2-recorder.d.ts

@@ -0,0 +1,39 @@
+/** 'o' = terminal output, 'i' = keyboard input, 'r' = terminal resize */
+export type AsciiCastV2EventCode = 'o' | 'i' | 'r';
+export interface AsciiCastV2Header {
+    version: 2;
+    width: number;
+    height: number;
+    timestamp?: number;
+    env?: {
+        [key: string]: string;
+    };
+}
+export type AsciiCastV2Event = [number, AsciiCastV2EventCode, string];
+export type AsciiCastV2Message = AsciiCastV2Header | AsciiCastV2Event;
+export interface AsciiCastV2RecorderOptions {
+    wsUrl: URL;
+    cols: number;
+    rows: number;
+    env?: {
+        [key: string]: string;
+    };
+    terminal: {
+        /** Register a callback for server output. Must return an unsubscribe function. */
+        onServerOutput: (callback: (data: string) => void) => () => void;
+    };
+}
+export declare class AsciiCastV2Recorder {
+    private initConfig;
+    private startTime;
+    private websocket;
+    private outputGeneration;
+    private unsubscribeOutput;
+    private settleStart;
+    constructor(initConfig: AsciiCastV2RecorderOptions);
+    start(): Promise<void>;
+    stop(): void;
+    private internalStop;
+    private onEvent;
+    private send;
+}

package/index.d.ts

@@ -0,0 +1,5 @@
+export type { AsciiCastV2Event, AsciiCastV2EventCode, AsciiCastV2Header, AsciiCastV2Message, AsciiCastV2RecorderOptions, } from './asciicast-v2-recorder';
+export { AsciiCastV2Recorder } from './asciicast-v2-recorder';
+export type { IRecordableSession } from './recordable-session';
+export type { WebMRecorderOptions, WebMRecorderTelemetryEvent } from './webm-recorder';
+export { WebMRecorder } from './webm-recorder';

package/index.js

@@ -0,0 +1,265 @@
+var g = Object.defineProperty;
+var m = (o, e, t) => e in o ? g(o, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : o[e] = t;
+var i = (o, e, t) => m(o, typeof e != "symbol" ? e + "" : e, t);
+class C {
+  constructor(e) {
+    i(this, "startTime", 0);
+    i(this, "websocket", null);
+    i(this, "outputGeneration", 0);
+    i(this, "unsubscribeOutput", null);
+    i(this, "settleStart", null);
+    this.initConfig = e;
+  }
+  // Resolves when the WebSocket opens and the asciicast header is sent.
+  // Rejects with an error string on any failure.
+  start() {
+    this.internalStop();
+    const { cols: e, rows: t, env: r, terminal: s } = this.initConfig, c = new URL(this.initConfig.wsUrl);
+    c.searchParams.set("fileType", "asciicast"), this.startTime = Date.now();
+    const d = ++this.outputGeneration;
+    let l, S = !1;
+    const u = new Promise((n, a) => {
+      l = (f) => {
+        S || (S = !0, this.settleStart = null, f !== void 0 ? a(f) : n());
+      };
+    });
+    this.settleStart = l;
+    let p = !1, h = null;
+    const R = () => {
+      !h || this.websocket !== h || (this.outputGeneration++, this.unsubscribeOutput && (this.unsubscribeOutput(), this.unsubscribeOutput = null), this.websocket = null, l(p ? "ConnectionToTheRecordingServerLost" : "UnableToConnectToTheRecordingServer"));
+    };
+    try {
+      h = new b(c.toString(), {
+        onOpen: () => {
+          this.websocket === h && (p = !0, l());
+        },
+        onError: R,
+        onClose: R
+      });
+    } catch (n) {
+      return console.error("[AsciiCastV2Recorder] Failed to create WebSocket:", n), l("UnableToConnectToTheRecordingServer"), u;
+    }
+    this.websocket = h, this.send({
+      version: 2,
+      timestamp: Math.floor(this.startTime / 1e3),
+      width: e,
+      height: t,
+      env: r
+    });
+    try {
+      this.unsubscribeOutput = s.onServerOutput((n) => {
+        if (this.outputGeneration !== d || !this.websocket)
+          return;
+        const a = n.replace(/\r?\n/g, `\r
+`);
+        this.onEvent("o", a);
+      });
+    } catch (n) {
+      console.error("[AsciiCastV2Recorder] Failed to subscribe to terminal output:", n);
+      const a = this.websocket;
+      return this.websocket = null, a == null || a.close(), l("UnableToStartRecording"), u;
+    }
+    return u;
+  }
+  stop() {
+    this.internalStop();
+  }
+  internalStop() {
+    var t;
+    this.outputGeneration++, this.unsubscribeOutput && (this.unsubscribeOutput(), this.unsubscribeOutput = null), (t = this.settleStart) == null || t.call(this), this.settleStart = null;
+    const e = this.websocket;
+    this.websocket = null, e == null || e.close();
+  }
+  onEvent(e, t) {
+    const r = (Date.now() - this.startTime) / 1e3;
+    this.send([r, e, t]);
+  }
+  send(e) {
+    var t;
+    (t = this.websocket) == null || t.send(JSON.stringify(e) + `
+`);
+  }
+}
+class b {
+  constructor(e, t) {
+    i(this, "ws");
+    i(this, "queue", []);
+    i(this, "ready", !1);
+    this.ws = new WebSocket(e), this.ws.onopen = () => {
+      var r;
+      this.ready = !0;
+      for (const s of this.queue)
+        this.ws.send(s);
+      this.queue = [], (r = t == null ? void 0 : t.onOpen) == null || r.call(t);
+    }, this.ws.onclose = () => {
+      var r;
+      this.ready = !1, this.queue = [], (r = t == null ? void 0 : t.onClose) == null || r.call(t);
+    }, this.ws.onerror = () => {
+      var r;
+      (r = t == null ? void 0 : t.onError) == null || r.call(t);
+    };
+  }
+  send(e) {
+    this.ws.readyState === WebSocket.CLOSING || this.ws.readyState === WebSocket.CLOSED || (this.ready ? this.ws.send(e) : this.queue.push(e));
+  }
+  close() {
+    this.ready = !1, this.queue = [], this.ws.readyState !== WebSocket.CLOSING && this.ws.readyState !== WebSocket.CLOSED && this.ws.close();
+  }
+}
+const w = 8, v = 10;
+class W {
+  constructor(e = {}) {
+    i(this, "mediaRecorder", null);
+    i(this, "ws", null);
+    i(this, "resolveStart", null);
+    i(this, "rejectStart", null);
+    i(this, "_isRecording", !1);
+    i(this, "stream", null);
+    i(this, "canvas", null);
+    i(this, "keepaliveRaf", null);
+    i(this, "keepaliveTick", !1);
+    i(this, "isStarting", !1);
+    i(this, "isCleaningUp", !1);
+    i(this, "pendingError", null);
+    this.options = e;
+  }
+  get isRecording() {
+    return this._isRecording;
+  }
+  // Resolves when the first data chunk is received (recording confirmed active).
+  // Rejects with an error string on any failure.
+  start(e, t) {
+    var s;
+    if (this._isRecording || this.isStarting || this.isCleaningUp)
+      return console.warn("[WebMRecorder] Recording already in progress or cleaning up"), Promise.reject("RecordingAlreadyInProgress");
+    const r = new Promise((c, d) => {
+      this.resolveStart = c, this.rejectStart = d;
+    });
+    return this.isStarting = !0, this.canvas = e, this.initializeCapture(e) ? (this.startStreaming(t), r) : (this.isStarting = !1, (s = this.rejectStart) == null || s.call(this, "UnableToStartRecording"), this.resolveStart = null, this.rejectStart = null, r);
+  }
+  stop() {
+    var e;
+    if (!this.isCleaningUp) {
+      if (this.isCleaningUp = !0, this.stopKeepalive(), this.mediaRecorder && this.mediaRecorder.state !== "inactive") {
+        this.mediaRecorder.stop();
+        return;
+      }
+      (e = this.resolveStart) == null || e.call(this), this.resolveStart = null, this.rejectStart = null, this.closeWebSocket(), this.cleanupResources(), this.fireTelemetry("recording-stopped");
+    }
+  }
+  // Initialize canvas capture stream
+  initializeCapture(e) {
+    if (!e)
+      return console.error("[WebMRecorder] Canvas element is null"), !1;
+    try {
+      this.stream = e.captureStream(w);
+    } catch (t) {
+      return console.error("Failed to initialize canvas capture:", t), !1;
+    }
+    return this.fireTelemetry("recording-initialized"), !0;
+  }
+  startStreaming(e) {
+    var t, r;
+    if (!this.stream) {
+      console.error("No capture stream initialized"), this.isStarting = !1, (t = this.rejectStart) == null || t.call(this, "UnableToStartRecording"), this.resolveStart = null, this.rejectStart = null;
+      return;
+    }
+    try {
+      this.initializeWebSocket(e);
+    } catch (s) {
+      console.error("[WebMRecorder] Failed to create WebSocket:", s), this.isStarting = !1, (r = this.rejectStart) == null || r.call(this, "UnableToConnectToTheRecordingServer"), this.resolveStart = null, this.rejectStart = null, this.cleanupResources();
+    }
+  }
+  initializeWebSocket(e) {
+    const t = e.includes("?") ? "&" : "?";
+    this.ws = new WebSocket(`${e}${t}fileType=webm`), this.ws.onopen = this.handleWebSocketOpen.bind(this), this.ws.onerror = this.handleWebSocketError.bind(this), this.ws.onclose = this.handleWebSocketClose.bind(this);
+  }
+  handleWebSocketOpen() {
+    var e, t;
+    if (!this.stream) {
+      this.isStarting = !1, (e = this.rejectStart) == null || e.call(this, "UnableToStartRecording"), this.resolveStart = null, this.rejectStart = null, this.closeWebSocket(), this.cleanupResources();
+      return;
+    }
+    try {
+      const r = new MediaRecorder(this.stream, { mimeType: "video/webm" });
+      this.mediaRecorder = r, r.onstart = this.handleMediaRecorderStart.bind(this), r.ondataavailable = this.handleMediaRecorderDataAvailable.bind(this), r.onstop = this.handleMediaRecorderStop.bind(this), r.onerror = this.handleMediaRecorderError.bind(this), r.start(v);
+    } catch (r) {
+      console.error("[WebMRecorder] Failed to start MediaRecorder:", r), this.isStarting = !1, (t = this.rejectStart) == null || t.call(this, "UnableToStartRecording"), this.resolveStart = null, this.rejectStart = null, this.closeWebSocket(), this.cleanupResources();
+    }
+  }
+  handleWebSocketClose(e) {
+    var s;
+    if (this.isCleaningUp)
+      return;
+    this.isCleaningUp = !0, this.stopKeepalive();
+    const r = this._isRecording || this.mediaRecorder !== null && this.mediaRecorder.state !== "inactive" ? "ConnectionToTheRecordingServerLost" : "UnableToConnectToTheRecordingServer";
+    if (this.mediaRecorder && this.mediaRecorder.state !== "inactive") {
+      this.pendingError = r, this.mediaRecorder.stop();
+      return;
+    }
+    console.warn("[WebMRecorder] WebSocket closed unexpectedly (no active recorder):", e), (s = this.rejectStart) == null || s.call(this, r), this.resolveStart = null, this.rejectStart = null, this.cleanupResources();
+  }
+  handleWebSocketError(e) {
+    var s;
+    if (console.error("[WebMRecorder] WebSocket error:", e), this.isCleaningUp) return;
+    this.isCleaningUp = !0, this.stopKeepalive();
+    const r = this._isRecording || this.mediaRecorder !== null && this.mediaRecorder.state !== "inactive" ? "ConnectionToTheRecordingServerLost" : "UnableToConnectToTheRecordingServer";
+    if (this.mediaRecorder && this.mediaRecorder.state !== "inactive") {
+      this.pendingError = r, this.mediaRecorder.stop();
+      return;
+    }
+    (s = this.rejectStart) == null || s.call(this, r), this.resolveStart = null, this.rejectStart = null, this.closeWebSocket(), this.cleanupResources();
+  }
+  // Browser captureStream implementations are unreliable for static or sparsely updated canvases.
+  // Drive the keepalive from rAF so the nudge is aligned with the rendering pipeline, and make a real
+  // change each frame so captureStream always has fresh canvas content to sample.
+  handleMediaRecorderStart() {
+    const e = () => {
+      this.nudgeCanvas(), this.keepaliveRaf = requestAnimationFrame(e);
+    };
+    this.keepaliveRaf = requestAnimationFrame(e);
+  }
+  // Nudge a single corner pixel with a *real* value change. A zero-alpha / no-op draw is elided by
+  // some engines' dirty-tracking (Edge 149 → empty WebM), so we alternate the pixel value. captureStream
+  // throttles the actual capture to CANVAS_STREAM_FPS regardless of the rAF rate. save()/restore() keeps
+  // this from leaking state onto the canvas's shared 2D context.
+  nudgeCanvas() {
+    var t;
+    const e = (t = this.canvas) == null ? void 0 : t.getContext("2d");
+    e && (e.save(), e.globalAlpha = 1, e.fillStyle = this.keepaliveTick ? "#000000" : "#000001", e.fillRect(0, 0, 1, 1), e.restore(), this.keepaliveTick = !this.keepaliveTick);
+  }
+  handleMediaRecorderDataAvailable(e) {
+    var t;
+    !e.data || e.data.size === 0 || (this._isRecording || (this.isStarting = !1, this._isRecording = !0, (t = this.resolveStart) == null || t.call(this), this.resolveStart = null, this.rejectStart = null), this.ws && this.ws.readyState === WebSocket.OPEN && this.ws.send(e.data));
+  }
+  handleMediaRecorderStop() {
+    var t, r;
+    this.closeWebSocket();
+    const e = this.pendingError;
+    e ? (t = this.rejectStart) == null || t.call(this, e) : (r = this.resolveStart) == null || r.call(this), this.resolveStart = null, this.rejectStart = null, this.cleanupResources(), e || this.fireTelemetry("recording-stopped");
+  }
+  handleMediaRecorderError(e) {
+    console.error("[WebMRecorder] MediaRecorder encountered an error:", e), !this.isCleaningUp && (this.isCleaningUp = !0, this.stopKeepalive(), this.pendingError = "UnableToStartRecording", this.mediaRecorder && this.mediaRecorder.state !== "inactive" && this.mediaRecorder.stop());
+  }
+  fireTelemetry(e) {
+    var t, r;
+    try {
+      (r = (t = this.options).onTelemetry) == null || r.call(t, e);
+    } catch (s) {
+      console.warn("[WebMRecorder] onTelemetry hook threw:", s);
+    }
+  }
+  cleanupResources() {
+    this._isRecording = !1, this.isStarting = !1, this.stopKeepalive(), this.ws && (this.ws.onopen = null, this.ws.onerror = null, this.ws.onclose = null), this.stream && (this.stream.getTracks().forEach((e) => e.stop()), this.stream = null), this.canvas = null, this.mediaRecorder && (this.mediaRecorder.onstart = null, this.mediaRecorder.ondataavailable = null, this.mediaRecorder.onstop = null, this.mediaRecorder.onerror = null), this.mediaRecorder = null, this.ws = null, this.resolveStart = null, this.rejectStart = null, this.pendingError = null, this.isCleaningUp = !1;
+  }
+  stopKeepalive() {
+    this.keepaliveRaf !== null && (cancelAnimationFrame(this.keepaliveRaf), this.keepaliveRaf = null);
+  }
+  closeWebSocket() {
+    this.ws && (this.ws.onclose = null, this.ws.onerror = null, (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING) && this.ws.close());
+  }
+}
+export {
+  C as AsciiCastV2Recorder,
+  W as WebMRecorder
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@devolutions/web-recorder",
+  "version": "0.1.0",
+  "description": "Framework-agnostic browser session-recording capture (WebM video + asciicast terminal) for Devolutions Gateway jrec push",
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "types": "./index.d.ts"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Devolutions/devolutions-gateway.git"
+  },
+  "keywords": [
+    "recording",
+    "session-recording",
+    "webm",
+    "asciicast",
+    "capture",
+    "media-recorder"
+  ],
+  "license": "MIT OR Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/recordable-session.d.ts

@@ -0,0 +1,3 @@
+export interface IRecordableSession {
+    shouldStartRecording: boolean;
+}

package/webm-recorder.d.ts

@@ -0,0 +1,38 @@
+export type WebMRecorderTelemetryEvent = 'recording-initialized' | 'recording-stopped';
+export interface WebMRecorderOptions {
+    onTelemetry?: (event: WebMRecorderTelemetryEvent) => void;
+}
+export declare class WebMRecorder {
+    private readonly options;
+    private mediaRecorder;
+    private ws;
+    private resolveStart;
+    private rejectStart;
+    private _isRecording;
+    private stream;
+    private canvas;
+    private keepaliveRaf;
+    private keepaliveTick;
+    private isStarting;
+    private isCleaningUp;
+    private pendingError;
+    constructor(options?: WebMRecorderOptions);
+    get isRecording(): boolean;
+    start(canvas: HTMLCanvasElement, recordingUrl: string): Promise<void>;
+    stop(): void;
+    private initializeCapture;
+    private startStreaming;
+    private initializeWebSocket;
+    private handleWebSocketOpen;
+    private handleWebSocketClose;
+    private handleWebSocketError;
+    private handleMediaRecorderStart;
+    private nudgeCanvas;
+    private handleMediaRecorderDataAvailable;
+    private handleMediaRecorderStop;
+    private handleMediaRecorderError;
+    private fireTelemetry;
+    private cleanupResources;
+    private stopKeepalive;
+    private closeWebSocket;
+}