Initialize smartkvm package

2026-05-16 13:41:55 +00:00
commit 8588c6c70d
18 changed files with 8751 additions and 0 deletions
@@ -0,0 +1,152 @@
+export type TKvmKind = 'jetkvm' | 'glinet' | 'pikvm' | 'tinypilot' | 'generic';
+
+export type TKvmFrameMimeType = 'image/png' | 'image/jpeg';
+
+export type TKvmOsHint = 'windows' | 'macos' | 'linux' | 'unknown';
+
+export type TKvmShellHint = 'powershell' | 'cmd' | 'bash' | 'zsh' | 'sh' | 'unknown';
+
+export type TKvmKey =
+  | 'Enter'
+  | 'Escape'
+  | 'Tab'
+  | 'Backspace'
+  | 'Delete'
+  | 'ArrowUp'
+  | 'ArrowDown'
+  | 'ArrowLeft'
+  | 'ArrowRight'
+  | 'Home'
+  | 'End'
+  | 'PageUp'
+  | 'PageDown'
+  | 'Space'
+  | 'Meta'
+  | 'Control'
+  | 'Alt'
+  | 'Shift'
+  | 'F1'
+  | 'F2'
+  | 'F3'
+  | 'F4'
+  | 'F5'
+  | 'F6'
+  | 'F7'
+  | 'F8'
+  | 'F9'
+  | 'F10'
+  | 'F11'
+  | 'F12'
+  | string;
+
+export interface IKvmFrame {
+  timestamp: number;
+  width: number;
+  height: number;
+  mimeType: TKvmFrameMimeType;
+  dataBase64: string;
+}
+
+export interface IBrowserKvmOptions {
+  url: string;
+  kind?: TKvmKind;
+  username?: string;
+  password?: string;
+  headless?: boolean;
+  /**
+   * Main element that should receive keyboard focus.
+   * Usually video, canvas, or a wrapper around the KVM viewer.
+   */
+  viewerSelector?: string;
+  /**
+   * Element used for frame capture.
+   * Defaults to video, then canvas, then viewer screenshot fallback.
+   */
+  captureSelector?: string;
+  /**
+   * Useful for self-signed KVM certificates.
+   */
+  ignoreHttpsErrors?: boolean;
+  /**
+   * Persist browser session cookies/login state.
+   */
+  userDataDir?: string;
+  /**
+   * Optional browser executable path.
+   */
+  executablePath?: string;
+  /**
+   * Optional timeout for initial load and viewer detection.
+   */
+  timeoutMs?: number;
+}
+
+export interface IKvmTypeTextOptions {
+  delayMs?: number;
+}
+
+export interface IKvmDriver {
+  readonly kind: TKvmKind;
+  connect: () => Promise<void>;
+  disconnect: () => Promise<void>;
+  focusViewer: () => Promise<void>;
+  captureFrame: () => Promise<IKvmFrame>;
+  typeText: (text: string, options?: IKvmTypeTextOptions) => Promise<void>;
+  pressKey: (key: TKvmKey) => Promise<void>;
+  pressShortcut: (keys: TKvmKey[]) => Promise<void>;
+  wait: (milliseconds: number) => Promise<void>;
+}
+
+export interface IOcrCrop {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface IOcrRecognizeOptions {
+  crop?: IOcrCrop;
+  language?: string;
+}
+
+export interface IOcrResult {
+  text: string;
+  confidence?: number;
+}
+
+export interface IOcrEngine {
+  recognize: (frame: IKvmFrame, options?: IOcrRecognizeOptions) => Promise<IOcrResult>;
+}
+
+export interface IKvmTerminalOptions {
+  kvm: IKvmDriver;
+  ocrEngine: IOcrEngine;
+  osHint?: TKvmOsHint;
+  shellHint?: TKvmShellHint;
+  commandTimeoutMs?: number;
+  ocrPollIntervalMs?: number;
+  ocrMaxAttempts?: number;
+  /**
+   * Optional OCR crop to limit recognition to terminal area.
+   */
+  ocrCrop?: IOcrCrop;
+}
+
+export interface IKvmTerminalCommandResult {
+  commandId: string;
+  command: string;
+  completed: boolean;
+  timedOut: boolean;
+  exitCode?: number;
+  combinedText: string;
+  rawOcrText: string;
+}
+
+export interface IWrappedKvmCommand {
+  commandId: string;
+  shellHint: TKvmShellHint;
+  command: string;
+  textToType: string;
+  startMarker: string;
+  endMarkerPrefix: string;
+}