@mks2508/mks-ui 0.3.2 → 0.5.0

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

@@ -0,0 +1,438 @@
+/**
+ * Terminal component types.
+ *
+ * Provides interfaces for the terminal component system supporting
+ * multiple renderers (xterm.js, restty) and PTY backends (node-pty,
+ * WebContainer) with configurable modes (interactive, read-only)
+ * and connection statuses.
+ *
+ * @module components/devenv/terminal/types
+ */
+
+/**
+ * Terminal renderer type - determines the rendering engine.
+ *
+ * - `xterm`: xterm.js DOM/canvas renderer (default, recommended for compatibility)
+ * - `restty`: GPU-accelerated WebGPU/WebGL2 renderer via restty with libghostty-vt WASM core
+ */
+export type ITerminalRendererType = 'xterm' | 'restty';
+
+/**
+ * Terminal PTY backend type - determines what drives the terminal server-side.
+ *
+ * - `nodepty`: node-pty via WebSocket (default, used by mks-devenv agent-backend)
+ * - `webcontainer`: @webcontainer/api for in-browser Node.js runtime
+ */
+export type ITerminalPtyBackendType = 'nodepty' | 'webcontainer';
+
+/**
+ * Terminal backend type - determines the rendering engine.
+ *
+ * @deprecated Use {@link ITerminalRendererType} for renderer selection
+ * and {@link ITerminalPtyBackendType} for backend selection instead.
+ *
+ * - `xterm`: xterm.js with WebSocket/SSE support (recommended)
+ * - `webcontainer`: @webcontainer/api for full Node.js in browser
+ * - `monaco`: Monaco Editor for Code-Server/Claude Code integration
+ */
+export type ITerminalBackendType = 'xterm' | 'webcontainer' | 'monaco';
+
+/**
+ * Terminal mode - determines user interaction capabilities.
+ *
+ * - `interactive`: Full terminal with input/output via WebSocket
+ * - `readonly`: Output-only mode via SSE for logs viewing
+ */
+export type ITerminalMode = 'interactive' | 'readonly';
+
+/**
+ * Connection status for WebSocket/SSE connections.
+ *
+ * Connection lifecycle states for terminal session management.
+ */
+export type ITerminalConnectionStatus =
+  | 'disconnected'
+  | 'connecting'
+  | 'connected'
+  | 'error';
+
+/**
+ * Terminal session information.
+ *
+ * Represents an active terminal session with metadata for
+ * multi-session management in the UI.
+ */
+export interface ITerminalSession {
+  /** Unique session identifier */
+  id: string;
+
+  /** Display name for the session (e.g., container name, workspace path) */
+  name: string;
+
+  /** Backend type rendering this session */
+  backend: ITerminalBackendType;
+
+  /** Renderer type for this session (default: 'xterm') */
+  renderer?: ITerminalRendererType;
+
+  /** Interaction mode for this session */
+  mode: ITerminalMode;
+
+  /** Current connection status */
+  status: ITerminalConnectionStatus;
+
+  /** Session creation timestamp */
+  createdAt: Date;
+
+  /** WebSocket URL for interactive mode (optional) */
+  wsUrl?: string;
+
+  /** SSE URL for readonly mode (optional) */
+  sseUrl?: string;
+}
+
+/**
+ * Terminal options for initialization.
+ *
+ * Configuration options passed to terminal backends during
+ * initialization. Includes xterm.js-specific options,
+ * WebSocket/SSE URLs, and lifecycle callbacks.
+ */
+export interface ITerminalOptions {
+  // Renderer & backend selection
+
+  /** Renderer type to use (default: 'xterm') */
+  renderer?: ITerminalRendererType;
+
+  /** PTY backend type (default: 'nodepty') */
+  ptyBackend?: ITerminalPtyBackendType;
+
+  /**
+   * Backend type to use (default: 'xterm').
+   * @deprecated Use {@link renderer} instead.
+   */
+  backend?: ITerminalBackendType;
+
+  /** Terminal mode (default: 'interactive') */
+  mode?: ITerminalMode;
+
+  // xterm.js options
+
+  /** Enable cursor blink animation (default: true) */
+  cursorBlink?: boolean;
+
+  /** Scrollback buffer size in lines (default: 1000) */
+  scrollback?: number;
+
+  /** Font size in pixels (default: 14) */
+  fontSize?: number;
+
+  /** Font family string (default: 'JetBrains Mono') */
+  fontFamily?: string;
+
+  /** Terminal theme colors */
+  theme?: ITerminalTheme;
+
+  // WebSocket/SSE configuration
+
+  /** WebSocket URL for interactive mode (ws:// or wss://) */
+  wsUrl?: string;
+
+  /** SSE URL for readonly mode (http:// or https://) */
+  sseUrl?: string;
+
+  // Callbacks
+
+  /** Called when user types input in interactive mode */
+  onData?: (data: string) => void;
+
+  /** Called on connection errors */
+  onError?: (error: Error) => void;
+
+  /** Called when connection closes */
+  onClose?: () => void;
+}
+
+/**
+ * Terminal theme matching Synthwave design system.
+ *
+ * Color palette for xterm.js rendering. Matches the mks-dev-environment
+ * design system from globals.css with background #241B2F, primary #D40C67,
+ * and success #44ffaa.
+ */
+export interface ITerminalTheme {
+  /** Background color (default: #241B2F - synthwave dark) */
+  background: string;
+
+  /** Default text color (default: #e8e8ec) */
+  foreground: string;
+
+  /** Cursor color (default: #D40C67 - primary magenta) */
+  cursor: string;
+
+  /** Cursor accent color for block cursor (optional) */
+  cursorAccent?: string;
+
+  /** Selection background color (optional) */
+  selectionBackground?: string;
+
+  /** Selection foreground color (optional, restty v0.1.24+) */
+  selectionForeground?: string;
+
+  /** ANSI color: black */
+  black: string;
+
+  /** ANSI color: red */
+  red: string;
+
+  /** ANSI color: green */
+  green: string;
+
+  /** ANSI color: yellow */
+  yellow: string;
+
+  /** ANSI color: blue */
+  blue: string;
+
+  /** ANSI color: magenta */
+  magenta: string;
+
+  /** ANSI color: cyan */
+  cyan: string;
+
+  /** ANSI color: white */
+  white: string;
+
+  /** ANSI bright color: bright black */
+  brightBlack: string;
+
+  /** ANSI bright color: bright red */
+  brightRed: string;
+
+  /** ANSI bright color: bright green */
+  brightGreen: string;
+
+  /** ANSI bright color: bright yellow */
+  brightYellow: string;
+
+  /** ANSI bright color: bright blue */
+  brightBlue: string;
+
+  /** ANSI bright color: bright magenta */
+  brightMagenta: string;
+
+  /** ANSI bright color: bright cyan */
+  brightCyan: string;
+
+  /** ANSI bright color: bright white */
+  brightWhite: string;
+}
+
+/**
+ * Capabilities that a terminal adapter supports.
+ *
+ * Used for runtime feature detection to adapt UI behavior
+ * based on the underlying renderer's capabilities.
+ */
+export interface ITerminalAdapterCapabilities {
+  /** Whether the adapter manages its own PTY WebSocket connection */
+  managesOwnConnection: boolean;
+
+  /** Whether the adapter supports GPU-accelerated rendering */
+  gpuRendering: boolean;
+
+  /** Whether the adapter supports built-in multi-pane splits */
+  multiPane: boolean;
+
+  /** Whether the adapter has a built-in theme catalog */
+  builtinThemes: boolean;
+}
+
+/**
+ * Terminal adapter interface - allows pluggable renderers.
+ *
+ * Abstraction layer for different terminal renderers (xterm.js, restty).
+ * All renderers must implement the core methods. Optional methods provide
+ * access to renderer-specific features when available (check `capabilities`).
+ */
+export interface ITerminalAdapter {
+  /** Backend type identifier */
+  type: ITerminalBackendType;
+
+  /** Adapter capabilities for runtime feature detection */
+  readonly capabilities: ITerminalAdapterCapabilities;
+
+  /**
+   * Initialize the terminal in the given container element.
+   *
+   * @param container - DOM element to render terminal into
+   * @param options - Terminal initialization options
+   * @returns Promise that resolves when terminal is ready
+   */
+  initialize(container: HTMLElement, options: ITerminalOptions): Promise<void>;
+
+  /**
+   * Write data to the terminal without newline.
+   * No-op for adapters that manage their own PTY connection (e.g. restty).
+   *
+   * @param data - String data to write
+   */
+  write(data: string): void;
+
+  /**
+   * Write data to the terminal with newline.
+   * No-op for adapters that manage their own PTY connection (e.g. restty).
+   *
+   * @param data - String data to write
+   */
+  writeln(data: string): void;
+
+  /**
+   * Clear the terminal buffer.
+   */
+  clear(): void;
+
+  /**
+   * Resize the terminal to the given dimensions.
+   *
+   * @param cols - Number of columns
+   * @param rows - Number of rows
+   */
+  resize(cols: number, rows: number): void;
+
+  /**
+   * Dispose of the terminal and release resources.
+   */
+  dispose(): void;
+
+  /**
+   * Switch between interactive and readonly modes.
+   *
+   * @param mode - Target mode
+   */
+  setMode(mode: ITerminalMode): void;
+
+  /**
+   * Focus the terminal for input.
+   */
+  focus(): void;
+
+  /**
+   * Remove focus from the terminal.
+   */
+  blur(): void;
+
+  /**
+   * Connect to a PTY backend via WebSocket URL.
+   * Only applicable when capabilities.managesOwnConnection is true.
+   *
+   * @param url - WebSocket URL for PTY connection
+   */
+  connectPty?(url: string): void;
+
+  /**
+   * Disconnect from the PTY backend.
+   * Only applicable when capabilities.managesOwnConnection is true.
+   */
+  disconnectPty?(): void;
+
+  /**
+   * Check if PTY WebSocket is connected.
+   * Only applicable when capabilities.managesOwnConnection is true.
+   */
+  isPtyConnected?(): boolean;
+
+  /**
+   * Update font size at runtime.
+   *
+   * @param size - Font size in pixels
+   */
+  setFontSize?(size: number): void;
+
+  /**
+   * Send raw input data to the terminal PTY.
+   * For adapters that manage their own connection.
+   *
+   * @param data - Input data string
+   */
+  sendInput?(data: string): void;
+
+  /**
+   * Copy the current text selection to the clipboard.
+   *
+   * @returns Whether the copy succeeded
+   */
+  copySelection?(): Promise<boolean>;
+
+  /**
+   * Paste clipboard contents into the terminal.
+   *
+   * @returns Whether the paste succeeded
+   */
+  pasteClipboard?(): Promise<boolean>;
+}
+
+/**
+ * PTY transport callbacks matching restty's PtyCallbacks contract.
+ * Consumers implement these to receive terminal events.
+ */
+export interface IPtyTransportCallbacks {
+  /** Called when WebSocket connection opens */
+  onConnect?: () => void;
+  /** Called when WebSocket connection closes */
+  onDisconnect?: () => void;
+  /** Called with terminal output data */
+  onData?: (data: string) => void;
+  /** Called when the server reports PTY status (shell name) */
+  onStatus?: (shell: string) => void;
+  /** Called when the server reports an error */
+  onError?: (message: string, errors?: string[]) => void;
+  /** Called when the PTY process exits */
+  onExit?: (code: number) => void;
+}
+
+/**
+ * PTY transport connect options matching restty's PtyConnectOptions.
+ */
+export interface IPtyTransportConnectOptions {
+  /** WebSocket URL (ws:// or wss://) */
+  url: string;
+  /** Initial terminal width in columns */
+  cols?: number;
+  /** Initial terminal height in rows */
+  rows?: number;
+  /** Event callbacks for connection lifecycle and data */
+  callbacks: IPtyTransportCallbacks;
+}
+
+/**
+ * PTY transport interface matching restty's expected contract.
+ * Consumers provide a custom implementation to bridge their WebSocket protocol.
+ */
+export interface IPtyTransport {
+  /** Open a connection to the PTY server */
+  connect: (options: IPtyTransportConnectOptions) => void;
+  /** Close the current connection */
+  disconnect: () => void;
+  /** Send terminal input data to the server */
+  sendInput: (data: string) => boolean;
+  /** Send terminal resize notification to the server */
+  resize: (cols: number, rows: number) => boolean;
+  /** Check if the transport is currently connected */
+  isConnected: () => boolean;
+  /** Release all resources held by the transport */
+  destroy: () => void;
+}
+
+/**
+ * Factory function that creates a PTY transport instance.
+ * Consumers inject this to provide custom WebSocket protocol bridging.
+ *
+ * @example
+ * ```ts
+ * // In mks-devenv consumer:
+ * const factory: IPtyTransportFactory = () => createDevenvPtyTransport();
+ * <TerminalRestty createPtyTransport={factory} wsUrl={wsUrl} />
+ * ```
+ */
+export type IPtyTransportFactory = () => IPtyTransport;

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

@@ -0,0 +1,38 @@
+/**
+ * TerminalDisplay style definitions.
+ *
+ * @module components/devenv/terminal/TerminalDisplay.styles
+ */
+
+import { cva, type VariantProps } from 'class-variance-authority';
+import type { StyleSlots } from '@/core/types';
+import type { TerminalDisplaySlot } from './TerminalDisplay.types';
+
+/**
+ * Default style slots for TerminalDisplay regions.
+ */
+export const terminalDisplayStyles: StyleSlots<TerminalDisplaySlot> = {
+  root: 'relative overflow-hidden',
+  chrome: '',
+  terminal: 'w-full h-full pointer-events-none',
+  emptyState: 'flex items-center justify-center text-sm text-muted-foreground/50 font-mono',
+};
+
+/**
+ * CVA variants for the display root.
+ */
+export const terminalDisplayVariants = cva(terminalDisplayStyles.root, {
+  variants: {
+    variant: {
+      default: '',
+      compact: '',
+      error: '',
+    },
+  },
+  defaultVariants: {
+    variant: 'default',
+  },
+});
+
+/** Extracted variant props type */
+export type TerminalDisplayVariantProps = VariantProps<typeof terminalDisplayVariants>;

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

@@ -0,0 +1,243 @@
+/**
+ * TerminalDisplay — Readonly GPU-rendered terminal for ANSI content.
+ *
+ * Uses restty directly (not xterm) for GPU-accelerated rendering of
+ * ANSI-formatted text without PTY connection. Content is written via
+ * `restty.sendInput(data, "pty")` which feeds text to the WASM terminal
+ * engine for parsing and rendering.
+ *
+ * Optionally wrapped in TerminalPanelChrome glassmorphism shell.
+ *
+ * @module components/devenv/terminal/TerminalDisplay
+ */
+
+'use client';
+
+import {
+  useRef,
+  useEffect,
+  useCallback,
+  forwardRef,
+  useImperativeHandle,
+  useState,
+} from 'react';
+import type { Restty } from 'restty';
+import type { ITerminalDisplayProps, ITerminalDisplayRef } from './TerminalDisplay.types';
+import { terminalDisplayStyles, terminalDisplayVariants } from './TerminalDisplay.styles';
+import { TerminalPanelChrome } from './panel/TerminalPanelChrome';
+import { getSynthwaveGhosttyTheme, xtermThemeToGhostty } from './Terminal.theme.restty';
+import { cn } from '@/react-ui/lib/utils';
+
+/**
+ * TerminalDisplay — Readonly restty terminal for displaying ANSI content.
+ *
+ * @example
+ * ```tsx
+ * <TerminalDisplay
+ *   content={"\x1b[31mError:\x1b[0m Something failed"}
+ *   title="Error Output"
+ *   variant="error"
+ *   fontSize={12}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Without chrome shell
+ * <TerminalDisplay
+ *   content={ansiOutput}
+ *   chrome={false}
+ *   minHeight={100}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With imperative handle
+ * const ref = useRef<ITerminalDisplayRef>(null);
+ * ref.current?.write("Additional output\r\n");
+ * ref.current?.clear();
+ * ```
+ */
+export const TerminalDisplay = forwardRef<ITerminalDisplayRef, ITerminalDisplayProps>(
+  (
+    {
+      content,
+      title = 'Output',
+      variant = 'default',
+      chrome = true,
+      fontSize = 13,
+      minHeight = 200,
+      theme,
+      resttyThemeName,
+      gpuRenderer = 'auto',
+      slots,
+      className,
+      emptyText,
+      onReady,
+    },
+    ref,
+  ) => {
+    const containerRef = useRef<HTMLDivElement>(null);
+    const resttyRef = useRef<Restty | null>(null);
+    const [isReady, setIsReady] = useState(false);
+
+    // Store callbacks in refs
+    const callbacksRef = useRef({ onReady });
+    callbacksRef.current = { onReady };
+
+    // Store content in ref to avoid re-creating restty on content change
+    const contentRef = useRef(content);
+    contentRef.current = content;
+
+    /**
+     * Initialize restty on mount.
+     * Dynamic import for SSR safety and code-splitting.
+     */
+    useEffect(() => {
+      if (!containerRef.current) return;
+      let destroyed = false;
+
+      const init = async () => {
+        const { Restty: ResttyClass, getBuiltinTheme } = await import('restty');
+        if (destroyed || !containerRef.current) return;
+
+        const restty = new ResttyClass({
+          root: containerRef.current,
+          appOptions: {
+            renderer: gpuRenderer,
+            fontSize,
+            autoResize: true,
+          },
+          fontSources: [
+            {
+              type: 'local',
+              matchers: [
+                'jetbrains mono',
+                'fira code',
+                'sf mono',
+                'cascadia code',
+                'meslo',
+              ],
+            },
+          ],
+          createInitialPane: true,
+          shortcuts: false,
+          defaultContextMenu: false,
+        });
+
+        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());
+        }
+
+        // Write initial content
+        if (contentRef.current) {
+          restty.sendInput(contentRef.current, 'pty');
+        }
+
+        setIsReady(true);
+        callbacksRef.current.onReady?.(restty);
+      };
+
+      init().catch(() => {
+        // Silently fail — container will show empty
+      });
+
+      return () => {
+        destroyed = true;
+        resttyRef.current?.destroy();
+        resttyRef.current = null;
+        setIsReady(false);
+      };
+    }, []); // Mount once
+
+    /**
+     * Re-write content when it changes after initialization.
+     */
+    useEffect(() => {
+      if (!isReady || !resttyRef.current) return;
+      resttyRef.current.clearScreen();
+      if (content) {
+        resttyRef.current.sendInput(content, 'pty');
+      }
+    }, [content, isReady]);
+
+    /**
+     * Handle fontSize changes after initialization.
+     */
+    useEffect(() => {
+      if (!isReady || !resttyRef.current) return;
+      resttyRef.current.setFontSize(fontSize);
+    }, [fontSize, isReady]);
+
+    /**
+     * Expose imperative handle.
+     */
+    useImperativeHandle(ref, () => ({
+      getRestty: () => resttyRef.current,
+      clear: () => resttyRef.current?.clearScreen(),
+      write: (data: string) => resttyRef.current?.sendInput(data, 'pty'),
+    }));
+
+    /** Map variant to chrome variant */
+    const chromeVariant = variant === 'error' ? 'error' : 'default';
+    const chromeSize = variant === 'compact' ? 'compact' : 'default';
+
+    /** The terminal content area */
+    const terminalElement = (
+      <div
+        className={cn(
+          terminalDisplayVariants({ variant }),
+          slots?.root,
+          className,
+        )}
+        style={{ minHeight: `${minHeight}px` }}
+      >
+        {/* Empty state */}
+        {!content && emptyText && (
+          <div
+            className={cn(terminalDisplayStyles.emptyState, slots?.emptyState)}
+            style={{ minHeight: `${minHeight}px` }}
+          >
+            {emptyText}
+          </div>
+        )}
+
+        {/* Restty container */}
+        <div
+          ref={containerRef}
+          className={cn(terminalDisplayStyles.terminal, slots?.terminal)}
+          style={{
+            minHeight: `${minHeight}px`,
+            display: !content && emptyText ? 'none' : undefined,
+          }}
+        />
+      </div>
+    );
+
+    if (!chrome) return terminalElement;
+
+    return (
+      <TerminalPanelChrome
+        containerName={title}
+        isConnected={isReady}
+        variant={chromeVariant}
+        size={chromeSize}
+        slots={{ root: slots?.chrome }}
+        className={className}
+      >
+        {terminalElement}
+      </TerminalPanelChrome>
+    );
+  },
+);
+
+TerminalDisplay.displayName = 'TerminalDisplay';