@mks2508/mks-ui 0.3.1 → 0.4.0

package/src/react-ui/blocks/Terminal/ResttyAdapter.ts

@@ -0,0 +1,278 @@
+/**
+ * ResttyAdapter - ITerminalAdapter implementation for restty.
+ *
+ * Wraps restty's GPU-accelerated terminal renderer into the
+ * pluggable adapter interface, enabling renderer switching in the UI.
+ *
+ * Key differences from XTermAdapter:
+ * - Restty manages its own PTY WebSocket via custom PtyTransport
+ * - GPU rendering (WebGPU/WebGL2) instead of DOM/canvas
+ * - No write()/writeln() for injecting display text — restty renders PTY output
+ * - Built-in multi-pane, theme catalog, and text shaping with ligatures
+ *
+ * @module components/devenv/terminal/ResttyAdapter
+ */
+
+import type {
+  ITerminalAdapter,
+  ITerminalAdapterCapabilities,
+  ITerminalBackendType,
+  ITerminalMode,
+  ITerminalOptions,
+  IPtyTransport,
+  IPtyTransportFactory,
+} from './Terminal.types';
+import type { Restty, ResttyPaneHandle } from 'restty';
+import { getSynthwaveGhosttyTheme, xtermThemeToGhostty } from './Terminal.theme.restty';
+
+/**
+ * ITerminalAdapter implementation backed by restty.
+ *
+ * Uses restty's Restty class with a custom DevenvPtyTransport
+ * that bridges the mks-devenv WebSocket JSON protocol. Status messages
+ * are not rendered in the terminal — they should be handled as React overlays.
+ *
+ * @example
+ * ```ts
+ * const adapter = new ResttyAdapter({ fontSize: 14 });
+ * await adapter.initialize(containerEl, options);
+ * adapter.connectPty?.('ws://localhost:3100/terminal/session-1');
+ * ```
+ */
+export class ResttyAdapter implements ITerminalAdapter {
+  /** Backend type identifier for factory pattern */
+  public readonly type: ITerminalBackendType = 'xterm'; // kept for backward compat with union
+
+  /** Adapter capabilities — restty manages its own connection and supports GPU */
+  public readonly capabilities: ITerminalAdapterCapabilities = {
+    managesOwnConnection: true,
+    gpuRendering: true,
+    multiPane: true,
+    builtinThemes: true,
+  };
+
+  private restty: Restty | null = null;
+  private transport: IPtyTransport | null = null;
+  private options: ITerminalOptions;
+  private rootElement: HTMLElement | null = null;
+  private createTransport?: IPtyTransportFactory;
+
+  /**
+   * @param options - Terminal initialization options
+   * @param createTransport - Optional factory to create a custom PTY transport.
+   *   If not provided, restty manages its own PTY connection internally.
+   */
+  constructor(options: ITerminalOptions, createTransport?: IPtyTransportFactory) {
+    this.options = options;
+    this.createTransport = createTransport;
+  }
+
+  /**
+   * Initialize restty in the given container element.
+   * Dynamically imports restty to enable code-splitting and SSR safety.
+   *
+   * @param container - DOM element to render the terminal into
+   * @param options - Terminal initialization options
+   */
+  async initialize(container: HTMLElement, options: ITerminalOptions): Promise<void> {
+    this.options = { ...this.options, ...options };
+    this.rootElement = container;
+
+    const { Restty } = await import('restty');
+
+    // Create custom PtyTransport if factory provided
+    this.transport = this.createTransport?.() ?? null;
+
+    this.restty = new Restty({
+      root: container,
+      appOptions: {
+        renderer: 'auto',
+        fontSize: this.options.fontSize ?? 14,
+        autoResize: true,
+        ...(this.transport ? { ptyTransport: this.transport } : {}),
+      },
+      fontSources: this.buildFontSources(),
+      createInitialPane: true,
+      shortcuts: false, // Disable built-in pane splitting shortcuts
+      defaultContextMenu: true,
+    });
+
+    // Apply theme
+    if (this.options.theme) {
+      this.restty.applyTheme(xtermThemeToGhostty(this.options.theme));
+    } else {
+      this.restty.applyTheme(getSynthwaveGhosttyTheme());
+    }
+  }
+
+  /**
+   * Write data to the terminal display.
+   * No-op for restty — it renders PTY output via its own connection.
+   * Status messages should be displayed as React overlays.
+   */
+  write(_data: string): void {
+    // No-op: restty renders from PTY stream, not injected text
+  }
+
+  /**
+   * Write data with newline to the terminal display.
+   * No-op for restty — see write().
+   */
+  writeln(_data: string): void {
+    // No-op: restty renders from PTY stream, not injected text
+  }
+
+  /**
+   * Clear the terminal screen and scrollback.
+   */
+  clear(): void {
+    this.restty?.clearScreen();
+  }
+
+  /**
+   * Resize the terminal to explicit dimensions.
+   * Uses Restty's native resize() (v0.1.21+) for precise control.
+   *
+   * @param cols - Number of columns
+   * @param rows - Number of rows
+   */
+  resize(cols: number, rows: number): void {
+    this.restty?.resize(cols, rows);
+  }
+
+  /**
+   * Dispose of restty and release all resources (GPU, WASM, WebSocket).
+   */
+  dispose(): void {
+    this.restty?.destroy();
+    this.restty = null;
+    this.transport = null;
+    this.rootElement = null;
+  }
+
+  /**
+   * Switch between interactive and readonly modes.
+   * No-op for restty — mode is determined by PTY connection state.
+   */
+  setMode(_mode: ITerminalMode): void {
+    // Restty doesn't have a separate readonly mode
+  }
+
+  /**
+   * Focus the terminal for keyboard input.
+   * Uses Restty's native focus() (v0.1.21+) which handles pane focus correctly.
+   */
+  focus(): void {
+    this.restty?.focus();
+  }
+
+  /**
+   * Remove focus from the terminal.
+   * Uses Restty's native blur() (v0.1.21+).
+   */
+  blur(): void {
+    this.restty?.blur();
+  }
+
+  /**
+   * Connect to a PTY backend via WebSocket URL.
+   *
+   * @param url - WebSocket URL for PTY connection
+   */
+  connectPty(url: string): void {
+    this.restty?.connectPty(url);
+  }
+
+  /**
+   * Disconnect from the PTY backend.
+   */
+  disconnectPty(): void {
+    this.restty?.disconnectPty();
+  }
+
+  /**
+   * Check if PTY WebSocket is connected.
+   */
+  isPtyConnected(): boolean {
+    return this.restty?.isPtyConnected() ?? false;
+  }
+
+  /**
+   * Update font size at runtime.
+   *
+   * @param size - Font size in CSS pixels
+   */
+  setFontSize(size: number): void {
+    this.restty?.setFontSize(size);
+  }
+
+  /**
+   * Send raw input data to the terminal PTY.
+   *
+   * @param data - Input data string
+   */
+  sendInput(data: string): void {
+    this.restty?.sendInput(data);
+  }
+
+  /**
+   * Copy the current text selection to the clipboard.
+   */
+  async copySelection(): Promise<boolean> {
+    return this.restty?.copySelectionToClipboard() ?? false;
+  }
+
+  /**
+   * Paste clipboard contents into the terminal.
+   */
+  async pasteClipboard(): Promise<boolean> {
+    return this.restty?.pasteFromClipboard() ?? false;
+  }
+
+  /**
+   * Get the underlying Restty instance for advanced usage.
+   * Use sparingly — prefer the adapter interface.
+   */
+  getResttyInstance(): Restty | null {
+    return this.restty;
+  }
+
+  /**
+   * Get the active pane handle for direct restty pane operations.
+   */
+  getActivePane(): ResttyPaneHandle | null {
+    return this.restty?.activePane() ?? null;
+  }
+
+  /**
+   * Build font source list following restty's priority pattern:
+   * local fonts first (fast), then CDN fallback.
+   */
+  private buildFontSources() {
+    const family = this.options.fontFamily;
+
+    if (family) {
+      // Parse comma-separated font family string into matchers
+      const matchers = family
+        .split(',')
+        .map((f) => f.trim().replace(/['"]/g, '').toLowerCase())
+        .filter(Boolean);
+
+      return [{ type: 'local' as const, matchers }];
+    }
+
+    // Default: prefer local system fonts commonly available in dev environments
+    return [
+      {
+        type: 'local' as const,
+        matchers: [
+          'jetbrains mono',
+          'fira code',
+          'sf mono',
+          'cascadia code',
+          'meslo',
+        ],
+      },
+    ];
+  }
+}

package/src/react-ui/blocks/Terminal/Terminal.adapter.ts

@@ -0,0 +1,97 @@
+/**
+ * Terminal adapter interface and factory.
+ *
+ * Allows switching between xterm.js, WebContainer, and Monaco backends
+ * through a unified interface. Backends are loaded dynamically to enable
+ * code-splitting and reduce initial bundle size.
+ *
+ * @module components/devenv/terminal/adapter
+ */
+
+import type {
+  ITerminalAdapter,
+  ITerminalBackendType,
+  ITerminalRendererType,
+  ITerminalOptions,
+} from './Terminal.types';
+
+/**
+ * Create terminal adapter based on backend type.
+ *
+ * Factory function that instantiates the appropriate terminal backend
+ * adapter. Currently only xterm.js is implemented, with WebContainer
+ * and Monaco planned for future releases.
+ *
+ * @param backend - Backend type to instantiate
+ * @param options - Terminal options to pass to the adapter
+ * @returns Promise resolving to the configured adapter
+ *
+ * @throws {Error} If backend type is not supported yet
+ *
+ * @example
+ * ```ts
+ * const adapter = await createTerminalAdapter('xterm', {
+ *   mode: 'interactive',
+ *   wsUrl: 'ws://localhost:3100/terminal/session-123',
+ * });
+ * await adapter.initialize(container, options);
+ * ```
+ */
+export async function createTerminalAdapter(
+  backend: ITerminalBackendType,
+  options: ITerminalOptions
+): Promise<ITerminalAdapter> {
+  switch (backend) {
+    case 'xterm':
+      const { XTermAdapter } = await import('./XTermAdapter');
+      return new XTermAdapter(options);
+
+    // TODO: Implement WebContainer and Monaco adapters
+    case 'webcontainer':
+    case 'monaco':
+      throw new Error(
+        `Backend '${backend}' is not yet implemented. Use 'xterm' backend for now.`
+      );
+
+    default:
+      throw new Error(`Unknown terminal backend: ${backend}`);
+  }
+}
+
+/**
+ * Create terminal adapter based on renderer type.
+ *
+ * Factory function that instantiates the appropriate terminal renderer
+ * adapter. Uses dynamic import for code-splitting — restty's WASM bundle
+ * is only loaded when the `'restty'` renderer is selected.
+ *
+ * @param renderer - Renderer type to instantiate
+ * @param options - Terminal options to pass to the adapter
+ * @returns Promise resolving to the configured adapter
+ *
+ * @example
+ * ```ts
+ * const adapter = await createTerminalAdapterForRenderer('restty', {
+ *   mode: 'interactive',
+ *   wsUrl: 'ws://localhost:3100/terminal/session-123',
+ * });
+ * await adapter.initialize(container, options);
+ * ```
+ */
+export async function createTerminalAdapterForRenderer(
+  renderer: ITerminalRendererType,
+  options: ITerminalOptions
+): Promise<ITerminalAdapter> {
+  switch (renderer) {
+    case 'restty': {
+      const { ResttyAdapter } = await import('./ResttyAdapter');
+      return new ResttyAdapter(options);
+    }
+
+    case 'xterm':
+    default: {
+      const { XTermAdapter } = await import('./XTermAdapter');
+      return new XTermAdapter(options);
+    }
+  }
+}

package/src/react-ui/blocks/Terminal/Terminal.theme.restty.ts

@@ -0,0 +1,155 @@
+/**
+ * Theme bridge between ITerminalTheme (xterm.js format) and GhosttyTheme (restty format).
+ *
+ * Converts the mks-dev-environment Synthwave theme colors into
+ * restty's Ghostty-compatible theme format for GPU-rendered terminals.
+ *
+ * @module components/devenv/terminal/theme-restty
+ */
+
+import type { ITerminalTheme } from './Terminal.types';
+import { SYNTHWAVE_TERMINAL_THEME } from './Terminal.theme';
+
+/**
+ * RGB color as used by restty's Ghostty theme format.
+ * Each channel is 0-255.
+ */
+export interface IResttyThemeColor {
+  r: number;
+  g: number;
+  b: number;
+  a?: number;
+}
+
+/**
+ * Ghostty theme structure compatible with restty's applyTheme().
+ * Mirrors the GhosttyTheme type from restty/theme.
+ */
+export interface IResttyGhosttyTheme {
+  name?: string;
+  colors: {
+    background?: IResttyThemeColor;
+    foreground?: IResttyThemeColor;
+    cursor?: IResttyThemeColor;
+    cursorText?: IResttyThemeColor;
+    selectionBackground?: IResttyThemeColor;
+    selectionForeground?: IResttyThemeColor;
+    palette: Array<IResttyThemeColor | undefined>;
+  };
+  raw: Record<string, string>;
+}
+
+/**
+ * Convert a hex color string (#RRGGBB or #RGB) to restty's ThemeColor format.
+ *
+ * @param hex - Hex color string (e.g., '#D40C67', '#fff')
+ * @returns RGB color object with channels 0-255
+ */
+export function hexToResttyColor(hex: string): IResttyThemeColor {
+  let clean = hex.replace('#', '');
+
+  // Handle shorthand (#RGB → #RRGGBB)
+  if (clean.length === 3) {
+    clean = clean[0] + clean[0] + clean[1] + clean[1] + clean[2] + clean[2];
+  }
+
+  return {
+    r: parseInt(clean.slice(0, 2), 16),
+    g: parseInt(clean.slice(2, 4), 16),
+    b: parseInt(clean.slice(4, 6), 16),
+  };
+}
+
+/**
+ * Convert an rgba() color string to restty's ThemeColor format.
+ * Falls back to opaque white for unparseable values.
+ *
+ * @param rgba - CSS rgba() string (e.g., 'rgba(0, 217, 255, 0.3)')
+ * @returns RGB color object
+ */
+function rgbaToResttyColor(rgba: string): IResttyThemeColor {
+  const match = rgba.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+)\s*)?\)/);
+  if (!match) return { r: 255, g: 255, b: 255 };
+
+  return {
+    r: parseInt(match[1], 10),
+    g: parseInt(match[2], 10),
+    b: parseInt(match[3], 10),
+    a: match[4] ? Math.round(parseFloat(match[4]) * 255) : undefined,
+  };
+}
+
+/**
+ * Parse any CSS color value (hex or rgba) to restty ThemeColor.
+ *
+ * @param color - CSS color string
+ * @returns RGB color object
+ */
+function cssColorToResttyColor(color: string): IResttyThemeColor {
+  if (color.startsWith('#')) return hexToResttyColor(color);
+  if (color.startsWith('rgb')) return rgbaToResttyColor(color);
+  return { r: 255, g: 255, b: 255 };
+}
+
+/**
+ * Convert ITerminalTheme (xterm.js format) to GhosttyTheme (restty format).
+ *
+ * Maps the 16-color ANSI palette plus background, foreground, cursor,
+ * and selection colors to restty's Ghostty theme structure.
+ *
+ * @param theme - xterm.js theme with hex color values
+ * @returns Ghostty theme compatible with restty's applyTheme()
+ */
+export function xtermThemeToGhostty(theme: ITerminalTheme): IResttyGhosttyTheme {
+  const palette: Array<IResttyThemeColor | undefined> = new Array(256).fill(undefined);
+
+  // Standard ANSI colors (indices 0-7)
+  palette[0] = hexToResttyColor(theme.black);
+  palette[1] = hexToResttyColor(theme.red);
+  palette[2] = hexToResttyColor(theme.green);
+  palette[3] = hexToResttyColor(theme.yellow);
+  palette[4] = hexToResttyColor(theme.blue);
+  palette[5] = hexToResttyColor(theme.magenta);
+  palette[6] = hexToResttyColor(theme.cyan);
+  palette[7] = hexToResttyColor(theme.white);
+
+  // Bright ANSI colors (indices 8-15)
+  palette[8] = hexToResttyColor(theme.brightBlack);
+  palette[9] = hexToResttyColor(theme.brightRed);
+  palette[10] = hexToResttyColor(theme.brightGreen);
+  palette[11] = hexToResttyColor(theme.brightYellow);
+  palette[12] = hexToResttyColor(theme.brightBlue);
+  palette[13] = hexToResttyColor(theme.brightMagenta);
+  palette[14] = hexToResttyColor(theme.brightCyan);
+  palette[15] = hexToResttyColor(theme.brightWhite);
+
+  return {
+    name: 'Synthwave Industrial Dark',
+    colors: {
+      background: hexToResttyColor(theme.background),
+      foreground: hexToResttyColor(theme.foreground),
+      cursor: hexToResttyColor(theme.cursor),
+      cursorText: theme.cursorAccent ? hexToResttyColor(theme.cursorAccent) : undefined,
+      selectionBackground: theme.selectionBackground
+        ? cssColorToResttyColor(theme.selectionBackground)
+        : undefined,
+      selectionForeground: theme.selectionForeground
+        ? cssColorToResttyColor(theme.selectionForeground)
+        : undefined,
+      palette,
+    },
+    raw: {},
+  };
+}
+
+/**
+ * Get the Synthwave Industrial Dark theme in Ghostty format for restty.
+ *
+ * Pre-built conversion of the default terminal theme, ready to pass
+ * directly to `restty.applyTheme()`.
+ *
+ * @returns GhosttyTheme with Synthwave colors
+ */
+export function getSynthwaveGhosttyTheme(): IResttyGhosttyTheme {
+  return xtermThemeToGhostty(SYNTHWAVE_TERMINAL_THEME);
+}

package/src/react-ui/blocks/Terminal/Terminal.theme.ts

@@ -0,0 +1,80 @@
+/**
+ * Synthwave Industrial Dark theme for xterm.js.
+ *
+ * Matches mks-dev-environment design system from globals.css:
+ * - background: #241B2F (220 25% 15%)
+ * - primary: #D40C67 (330 85% 43%)
+ * - success: #44ffaa (142 100% 62%)
+ *
+ * Color palette optimized for dark terminal with high contrast
+ * and cyberpunk/synthwave aesthetic.
+ *
+ * @module components/devenv/terminal/theme
+ */
+
+import type { ITerminalTheme } from './Terminal.types';
+
+/**
+ * Synthwave Industrial Dark theme for xterm.js.
+ *
+ * Features:
+ * - Deep purple background (#241B2F) matching design system
+ * - Primary magenta cursor (#D40C67) with glow effect support
+ * - High-contrast ANSI colors for readability
+ * - Cyan selection with transparency for visual feedback
+ */
+export const SYNTHWAVE_TERMINAL_THEME: ITerminalTheme = {
+  // Base colors from design system
+  background: '#241B2F',
+  foreground: '#e8e8ec',
+
+  // Cursor - primary magenta with glow effect
+  cursor: '#D40C67',
+  cursorAccent: '#D40C67',
+
+  // Selection - cyan with transparency
+  selectionBackground: 'rgba(0, 217, 255, 0.3)',
+
+  // ANSI colors - adjusted for synthwave aesthetic
+  black: '#1a1a2e',
+  red: '#ff4466',
+  green: '#44ffaa',
+  yellow: '#ffcc00',
+  blue: '#00d9ff',
+  magenta: '#D40C67',
+  cyan: '#00d9ff',
+  white: '#e8e8ec',
+
+  // Bright ANSI colors - enhanced for better visibility
+  brightBlack: '#2d2d44',
+  brightRed: '#ff6b6b',
+  brightGreen: '#66ffcc',
+  brightYellow: '#ffdd33',
+  brightBlue: '#33e0ff',
+  brightMagenta: '#ff3399',
+  brightCyan: '#33e0ff',
+  brightWhite: '#ffffff',
+};
+
+/**
+ * Get terminal theme with optional overrides.
+ *
+ * Allows customizing the Synthwave theme while preserving
+ * the default color scheme. Useful for per-session theming.
+ *
+ * @param overrides - Partial theme properties to override
+ * @returns Complete terminal theme with applied overrides
+ *
+ * @example
+ * ```ts
+ * const customTheme = getTerminalTheme({
+ *   cursor: '#00ff00',
+ *   fontSize: 16,
+ * });
+ * ```
+ */
+export function getTerminalTheme(
+  overrides?: Partial<ITerminalTheme>
+): ITerminalTheme {
+  return { ...SYNTHWAVE_TERMINAL_THEME, ...overrides };
+}