@mks2508/mks-ui 0.3.2 → 0.5.0

package/src/react-ui/blocks/Terminal/TerminalDisplay.types.ts

@@ -0,0 +1,73 @@
+/**
+ * TerminalDisplay component types.
+ *
+ * Readonly GPU-rendered terminal for displaying ANSI-formatted text
+ * without PTY connection, using restty.
+ *
+ * @module components/devenv/terminal/TerminalDisplay.types
+ */
+
+import type { SlotOverrides } from '@/core/types';
+import type { Restty } from 'restty';
+import type { ITerminalTheme } from './Terminal.types';
+
+/** Slot names for TerminalDisplay sub-regions */
+export type TerminalDisplaySlot = 'root' | 'chrome' | 'terminal' | 'emptyState';
+
+/**
+ * Props for TerminalDisplay component.
+ */
+export interface ITerminalDisplayProps {
+  /** ANSI-formatted string content to display */
+  content: string;
+
+  /** Title shown in the chrome header */
+  title?: string;
+
+  /** Visual variant — 'error' uses red accent line */
+  variant?: 'default' | 'compact' | 'error';
+
+  /** Whether to show the glassmorphism chrome shell (default: true) */
+  chrome?: boolean;
+
+  /** Font size in CSS pixels (default: 13) */
+  fontSize?: number;
+
+  /** Minimum height in CSS pixels (default: 200) */
+  minHeight?: number;
+
+  /** Terminal theme in xterm.js format (auto-converted to Ghostty) */
+  theme?: ITerminalTheme;
+
+  /** Restty built-in theme name from the 458-theme catalog */
+  resttyThemeName?: string;
+
+  /** GPU renderer preference (default: 'auto') */
+  gpuRenderer?: 'auto' | 'webgpu' | 'webgl2';
+
+  /** Slot class overrides for each visual region */
+  slots?: SlotOverrides<TerminalDisplaySlot>;
+
+  /** Custom class name on root element */
+  className?: string;
+
+  /** Placeholder text when content is empty */
+  emptyText?: string;
+
+  /** Callback when restty instance is ready */
+  onReady?: (restty: Restty) => void;
+}
+
+/**
+ * Imperative handle for TerminalDisplay.
+ */
+export interface ITerminalDisplayRef {
+  /** Get the underlying Restty instance */
+  getRestty: () => Restty | null;
+
+  /** Clear the terminal display */
+  clear: () => void;
+
+  /** Write additional ANSI content (appends) */
+  write: (data: string) => void;
+}

package/src/react-ui/blocks/Terminal/TerminalPanel.tsx

@@ -0,0 +1,269 @@
+/**
+ * Terminal Panel Component.
+ *
+ * Main UI component with toolbar, terminal display, and status indicator.
+ * Configurable backend adapter (xterm.js, WebContainer, Monaco) with
+ * Synthwave Industrial Dark theme matching the design system.
+ *
+ * @module components/devenv/terminal
+ */
+
+'use client';
+
+import { useState, useCallback, useRef, useEffect } from 'react';
+import { XTermWrapper } from './TerminalXterm';
+import { getTerminalTheme } from './Terminal.theme';
+import { TerminalIcon } from '@/react-ui/icons/lucide-animated';
+import type { ITerminalBackendType, ITerminalMode } from './Terminal.types';
+
+/**
+ * Props for the TerminalPanel component.
+ */
+export interface ITerminalPanelProps {
+  /** Backend type to use (default: 'xterm') */
+  backend?: ITerminalBackendType;
+
+  /** Terminal mode (default: 'interactive') */
+  mode?: ITerminalMode;
+
+  /** WebSocket URL for interactive mode */
+  wsUrl?: string;
+
+  /** SSE URL for readonly mode */
+  sseUrl?: string;
+
+  /** Custom class name for styling */
+  className?: string;
+
+  /** Display title (default: 'Terminal') */
+  title?: string;
+
+  /** Show/hide toolbar (default: true) */
+  showToolbar?: boolean;
+
+  /** Enable search functionality (default: true) */
+  enableSearch?: boolean;
+
+  /** Callback when connection status changes */
+  onStatusChange?: (status: 'connected' | 'disconnected' | 'error' | 'connecting') => void;
+
+  /** Callback when user types data */
+  onData?: (data: string) => void;
+}
+
+/**
+ * Connection status type for state management.
+ */
+type TConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+
+/**
+ * Terminal Panel Component.
+ *
+ * Full-featured terminal UI with toolbar, status indicator, search,
+ * and xterm.js integration. Supports both interactive (WebSocket)
+ * and readonly (SSE) modes with proper cleanup and error handling.
+ *
+ * @example
+ * ```tsx
+ * // Interactive mode with WebSocket
+ * <TerminalPanel
+ *   mode="interactive"
+ *   wsUrl="ws://localhost:3100/api/terminal/session-123"
+ *   onData={(data) => sendMessage({ type: 'input', data })}
+ * />
+ *
+ * // Readonly mode with SSE
+ * <TerminalPanel
+ *   mode="readonly"
+ *   sseUrl="http://localhost:3100/api/logs/containers/devenv/stream"
+ * />
+ * ```
+ */
+export function TerminalPanel({
+  backend = 'xterm',
+  mode = 'interactive',
+  wsUrl,
+  sseUrl,
+  className,
+  title = 'Terminal',
+  showToolbar = true,
+  onStatusChange,
+  onData,
+}: ITerminalPanelProps) {
+  const [status, setStatus] = useState<TConnectionStatus>('disconnected');
+  const terminalRef = useRef<any>(null);
+  const wsRef = useRef<WebSocket | null>(null);
+  const eventSourceRef = useRef<EventSource | null>(null);
+
+  /**
+   * Update connection status and notify parent.
+   */
+  const updateStatus = useCallback(
+    (newStatus: TConnectionStatus) => {
+      setStatus(newStatus);
+      onStatusChange?.(newStatus);
+    },
+    [onStatusChange]
+  );
+
+  /**
+   * Handle terminal data input from user.
+   */
+  const handleData = useCallback(
+    (data: string) => {
+      // Send to parent callback
+      onData?.(data);
+
+      // Send to WebSocket if connected
+      if (mode === 'interactive' && wsRef.current?.readyState === WebSocket.OPEN) {
+        wsRef.current.send(data);
+      }
+    },
+    [mode, onData]
+  );
+
+  /**
+   * Handle terminal ready state.
+   */
+  const handleReady = useCallback(
+    (terminal: any) => {
+      terminalRef.current = terminal;
+      updateStatus('connected');
+
+      // Establish WebSocket or SSE connection
+      if (mode === 'interactive' && wsUrl) {
+        connectWebSocket(wsUrl);
+      } else if (mode === 'readonly' && sseUrl) {
+        connectSSE(sseUrl);
+      }
+    },
+    [mode, wsUrl, sseUrl, updateStatus]
+  );
+
+  /**
+   * Establish WebSocket connection for interactive mode.
+   */
+  const connectWebSocket = useCallback((url: string) => {
+    updateStatus('connecting');
+
+    const ws = new WebSocket(url);
+    wsRef.current = ws;
+
+    ws.onopen = () => {
+      updateStatus('connected');
+    };
+
+    ws.onmessage = (event) => {
+      terminalRef.current?.write(event.data);
+    };
+
+    ws.onerror = () => {
+      updateStatus('error');
+    };
+
+    ws.onclose = () => {
+      updateStatus('disconnected');
+    };
+  }, [updateStatus]);
+
+  /**
+   * Establish SSE connection for readonly mode.
+   */
+  const connectSSE = useCallback((url: string) => {
+    updateStatus('connecting');
+
+    const eventSource = new EventSource(url);
+    eventSourceRef.current = eventSource;
+
+    eventSource.onopen = () => {
+      updateStatus('connected');
+    };
+
+    eventSource.onmessage = (event) => {
+      terminalRef.current?.writeln(event.data);
+    };
+
+    eventSource.onerror = () => {
+      updateStatus('error');
+      eventSource.close();
+    };
+  }, [updateStatus]);
+
+  /**
+   * Cleanup connections on unmount.
+   */
+  useEffect(() => {
+    return () => {
+      wsRef.current?.close();
+      eventSourceRef.current?.close();
+    };
+  }, []);
+
+  /**
+   * Get status color class.
+   */
+  const getStatusColor = (): string => {
+    switch (status) {
+      case 'connected':
+        return 'text-success';
+      case 'error':
+        return 'text-destructive';
+      case 'connecting':
+        return 'text-warning';
+      default:
+        return 'text-muted-foreground';
+    }
+  };
+
+  return (
+    <section className={className}>
+      {/* Toolbar */}
+      {showToolbar && (
+        <div className="flex items-center justify-between mb-2 px-2">
+          {/* Left: Title and Status */}
+          <div className="flex items-center gap-2">
+            <TerminalIcon className="w-4 h-4 text-primary" />
+            <h2 className="text-sm font-semibold font-mono text-foreground">{title}</h2>
+
+            {/* Status Badge */}
+            <span
+              className={`text-xs font-mono font-medium ${getStatusColor()}`}
+              data-terminal-status
+            >
+              {status.toUpperCase()}
+            </span>
+          </div>
+
+          {/* Right: Toolbar Actions */}
+          <div className="flex items-center gap-1" />
+        </div>
+      )}
+
+      {/* Terminal Display */}
+      <XTermWrapper
+        options={{
+          backend,
+          mode,
+          wsUrl,
+          sseUrl,
+          onData: handleData,
+          onError: (error) => {
+            console.error('[TerminalPanel] Error:', error);
+            updateStatus('error');
+          },
+        }}
+        theme={getTerminalTheme()}
+        onReady={handleReady}
+      />
+
+      {/* Footer with hints */}
+      {mode === 'interactive' && status === 'connected' && (
+        <div className="mt-2 px-2 flex items-center justify-between text-xs text-muted-foreground font-mono">
+          <span>Ctrl+C to interrupt • Ctrl+D to exit</span>
+          <span>{terminalRef.current?.cols ?? 0}x{terminalRef.current?.rows ?? 0}</span>
+        </div>
+      )}
+    </section>
+  );
+}
+

package/src/react-ui/blocks/Terminal/TerminalRestty.tsx

@@ -0,0 +1,326 @@
+/**
+ * TerminalRestty - React wrapper for restty GPU terminal renderer.
+ *
+ * Manages the restty lifecycle within React's component model,
+ * handling mount/unmount, dynamic import (SSR-safe), font loading,
+ * theme application, and PTY connection via custom DevenvPtyTransport.
+ *
+ * @module components/devenv/terminal/TerminalRestty
+ */
+
+'use client';
+
+import {
+  useRef,
+  useEffect,
+  useCallback,
+  forwardRef,
+  useImperativeHandle,
+  useState,
+} from 'react';
+import type { Restty } from 'restty';
+import type { ITerminalTheme, IPtyTransport, IPtyTransportFactory } from './Terminal.types';
+import { getSynthwaveGhosttyTheme, xtermThemeToGhostty } from './Terminal.theme.restty';
+
+/**
+ * Props for the TerminalRestty React wrapper.
+ */
+export interface ITerminalResttyProps {
+  /**
+   * Factory to create a custom PTY transport.
+   * If not provided, restty manages its own PTY connection internally.
+   * Use this to inject custom WebSocket protocol bridging (e.g., mks-devenv).
+   */
+  createPtyTransport?: IPtyTransportFactory;
+
+  /** PTY WebSocket URL to connect to */
+  wsUrl?: string;
+
+  /** Font size in CSS pixels (default: 14) */
+  fontSize?: number;
+
+  /** Terminal theme in xterm.js format (auto-converted to Ghostty format) */
+  theme?: ITerminalTheme;
+
+  /**
+   * Restty built-in theme name from the 458-theme catalog.
+   * Takes precedence over the `theme` prop when set.
+   */
+  resttyThemeName?: string;
+
+  /**
+   * GPU renderer preference.
+   * - `auto`: WebGPU with WebGL2 fallback (default, recommended)
+   * - `webgpu`: Force WebGPU only
+   * - `webgl2`: Force WebGL2 only
+   */
+  gpuRenderer?: 'auto' | 'webgpu' | 'webgl2';
+
+  /** Callback when restty instance is initialized and ready */
+  onReady?: (restty: Restty) => void;
+
+  /** Callback when terminal dimensions change */
+  onResize?: (cols: number, rows: number) => void;
+
+  /** Callback when PTY connection status changes */
+  onPtyStatus?: (status: string) => void;
+
+  /** Callback when PTY connection opens */
+  onConnect?: () => void;
+
+  /** Callback when PTY connection closes */
+  onDisconnect?: () => void;
+
+  /** Callback when PTY reports an error */
+  onError?: (message: string) => void;
+
+  /**
+   * Callback when the terminal receives a desktop notification (OSC 9/777).
+   * Available in restty v0.1.24+.
+   *
+   * @param notification - Notification data with title, body, and paneId
+   */
+  onDesktopNotification?: (notification: { title?: string; body?: string; paneId: number }) => void;
+
+  /** Custom class name for the container div */
+  className?: string;
+}
+
+/**
+ * Imperative handle for TerminalRestty component.
+ */
+export interface ITerminalResttyRef {
+  /** Get the underlying Restty instance */
+  getRestty: () => Restty | null;
+
+  /** Send raw input to the terminal PTY */
+  sendInput: (data: string) => void;
+
+  /** Clear the terminal screen */
+  clear: () => void;
+
+  /** Focus the terminal for keyboard input */
+  focus: () => void;
+
+  /** Remove focus from the terminal */
+  blur: () => void;
+
+  /** Update font size */
+  setFontSize: (size: number) => void;
+
+  /** Resize terminal to explicit dimensions (v0.1.21+) */
+  resize: (cols: number, rows: number) => void;
+
+  /** Check if PTY is connected */
+  isPtyConnected: () => boolean;
+
+  /** Connect to a PTY URL */
+  connectPty: (url: string) => void;
+
+  /** Disconnect from PTY */
+  disconnectPty: () => void;
+}
+
+/**
+ * TerminalRestty - React component wrapping restty's GPU terminal.
+ *
+ * Handles the full lifecycle: dynamic WASM/WebGPU import, font loading,
+ * theme application, PTY connection via custom transport, and cleanup.
+ *
+ * @example
+ * ```tsx
+ * const resttyRef = useRef<ITerminalResttyRef>(null);
+ *
+ * <TerminalRestty
+ *   ref={resttyRef}
+ *   wsUrl="ws://localhost:3100/terminal/session-1"
+ *   fontSize={14}
+ *   onResize={(cols, rows) => console.log(`${cols}x${rows}`)}
+ *   onConnect={() => console.log('PTY connected')}
+ * />
+ * ```
+ */
+export const TerminalRestty = forwardRef<ITerminalResttyRef, ITerminalResttyProps>(
+  (
+    {
+      createPtyTransport,
+      wsUrl,
+      fontSize = 14,
+      theme,
+      resttyThemeName,
+      gpuRenderer = 'auto',
+      onReady,
+      onResize,
+      onPtyStatus,
+      onConnect,
+      onDisconnect,
+      onError,
+      onDesktopNotification,
+      className,
+    },
+    ref
+  ) => {
+    const containerRef = useRef<HTMLDivElement>(null);
+    const resttyRef = useRef<Restty | null>(null);
+    const transportRef = useRef<IPtyTransport | null>(null);
+    const [isInitialized, setIsInitialized] = useState(false);
+
+    // Store callbacks in refs to avoid re-creating restty on callback changes
+    const callbacksRef = useRef({ onReady, onResize, onPtyStatus, onConnect, onDisconnect, onError, onDesktopNotification });
+    callbacksRef.current = { onReady, onResize, onPtyStatus, onConnect, onDisconnect, onError, onDesktopNotification };
+
+    /**
+     * Initialize restty on mount.
+     * Dynamic import ensures SSR safety (WASM + WebGPU require browser).
+     */
+    useEffect(() => {
+      if (!containerRef.current) return;
+      let destroyed = false;
+
+      const initRestty = async () => {
+        const { Restty, getBuiltinTheme } = await import('restty');
+        if (destroyed || !containerRef.current) return;
+
+        // Create custom PtyTransport if factory provided
+        const transport = createPtyTransport?.() ?? null;
+        transportRef.current = transport;
+
+        const restty = new Restty({
+          root: containerRef.current,
+          appOptions: {
+            renderer: gpuRenderer,
+            fontSize,
+            autoResize: true,
+            ...(transport ? { ptyTransport: transport } : {}),
+            callbacks: {
+              onTermSize: (cols: number, rows: number) => {
+                callbacksRef.current.onResize?.(cols, rows);
+              },
+              onPtyStatus: (status: string) => {
+                callbacksRef.current.onPtyStatus?.(status);
+              },
+            },
+          },
+          fontSources: [
+            {
+              type: 'local',
+              matchers: [
+                'jetbrains mono',
+                'fira code',
+                'sf mono',
+                'cascadia code',
+                'meslo',
+              ],
+            },
+          ],
+          onDesktopNotification: (notification: { title?: string; body?: string; paneId: number }) => {
+            callbacksRef.current.onDesktopNotification?.(notification);
+          },
+          createInitialPane: true,
+          shortcuts: false,
+          defaultContextMenu: true,
+        });
+
+        resttyRef.current = restty;
+
+        // Apply theme
+        if (resttyThemeName) {
+          const builtinTheme = getBuiltinTheme(resttyThemeName);
+          if (builtinTheme) restty.applyTheme(builtinTheme);
+        } else if (theme) {
+          restty.applyTheme(xtermThemeToGhostty(theme));
+        } else {
+          restty.applyTheme(getSynthwaveGhosttyTheme());
+        }
+
+        // Connect to PTY if URL provided
+        if (wsUrl) {
+          restty.connectPty(wsUrl);
+        }
+
+        setIsInitialized(true);
+        callbacksRef.current.onReady?.(restty);
+      };
+
+      initRestty().catch((err) => {
+        if (!destroyed) {
+          callbacksRef.current.onError?.(
+            `Failed to initialize restty: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      });
+
+      return () => {
+        destroyed = true;
+        resttyRef.current?.destroy();
+        resttyRef.current = null;
+        transportRef.current = null;
+        setIsInitialized(false);
+      };
+    }, []); // Mount once — prop changes handled by separate effects
+
+    /**
+     * Handle wsUrl changes after initialization.
+     */
+    useEffect(() => {
+      if (!isInitialized || !resttyRef.current) return;
+
+      if (wsUrl) {
+        resttyRef.current.disconnectPty();
+        resttyRef.current.connectPty(wsUrl);
+      } else {
+        resttyRef.current.disconnectPty();
+      }
+    }, [wsUrl, isInitialized]);
+
+    /**
+     * Handle fontSize changes after initialization.
+     */
+    useEffect(() => {
+      if (!isInitialized || !resttyRef.current) return;
+      resttyRef.current.setFontSize(fontSize);
+    }, [fontSize, isInitialized]);
+
+    /**
+     * Handle theme changes after initialization.
+     */
+    useEffect(() => {
+      if (!isInitialized || !resttyRef.current) return;
+
+      if (resttyThemeName) {
+        import('restty').then(({ getBuiltinTheme }) => {
+          const builtinTheme = getBuiltinTheme(resttyThemeName);
+          if (builtinTheme) resttyRef.current?.applyTheme(builtinTheme);
+        });
+      } else if (theme) {
+        resttyRef.current.applyTheme(xtermThemeToGhostty(theme));
+      }
+    }, [theme, resttyThemeName, isInitialized]);
+
+    /**
+     * Expose imperative handle for parent component control.
+     */
+    useImperativeHandle(ref, () => ({
+      getRestty: () => resttyRef.current,
+      sendInput: (data: string) => resttyRef.current?.sendInput(data),
+      clear: () => resttyRef.current?.clearScreen(),
+      focus: () => resttyRef.current?.focus(),
+      blur: () => resttyRef.current?.blur(),
+      setFontSize: (size: number) => resttyRef.current?.setFontSize(size),
+      resize: (cols: number, rows: number) => resttyRef.current?.resize(cols, rows),
+      isPtyConnected: () => resttyRef.current?.isPtyConnected() ?? false,
+      connectPty: (url: string) => resttyRef.current?.connectPty(url),
+      disconnectPty: () => resttyRef.current?.disconnectPty(),
+    }));
+
+    return (
+      <div
+        ref={containerRef}
+        className={className}
+        style={{ width: '100%', height: '100%', minHeight: '400px' }}
+      />
+    );
+  }
+);
+
+TerminalRestty.displayName = 'TerminalRestty';