@mks2508/mks-ui 0.5.7 → 0.6.0

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

@@ -1,326 +0,0 @@
-/**
- * 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';

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

@@ -1,230 +0,0 @@
-/**
- * xterm.js wrapper component.
- *
- * Encapsulates xterm.js initialization, addon loading,
- * and cleanup following React best practices with proper
- * ref management and effect hooks.
- *
- * @module components/devenv/terminal/xterm
- */
-
-'use client';
-
-import { useEffect, useRef, useCallback } from 'react';
-import { Terminal } from '@xterm/xterm';
-import { FitAddon } from '@xterm/addon-fit';
-import { WebLinksAddon } from '@xterm/addon-web-links';
-import { SearchAddon } from '@xterm/addon-search';
-import { Unicode11Addon } from '@xterm/addon-unicode11';
-import type { ITerminalOptions, ITerminalTheme } from './Terminal.types';
-import '@xterm/xterm/css/xterm.css';
-
-/**
- * Props for the XTermWrapper component.
- */
-export interface IXTermWrapperProps {
-  /** Terminal initialization options */
-  options: ITerminalOptions;
-
-  /** Terminal theme (defaults to Synthwave if not provided) */
-  theme?: ITerminalTheme;
-
-  /** Callback when user types data in interactive mode */
-  onData?: (data: string) => void;
-
-  /** Callback when terminal is ready for interaction */
-  onReady?: (terminal: Terminal) => void;
-
-  /** Callback when terminal resizes */
-  onResize?: (cols: number, rows: number) => void;
-
-  /** Custom class name for the container */
-  className?: string;
-}
-
-/**
- * xterm.js wrapper component.
- *
- * Manages xterm.js lifecycle including initialization, addon loading,
- * WebSocket/SSE connections, and cleanup. Provides auto-resize via
- * FitAddon and clickable URLs via WebLinksAddon.
- *
- * @example
- * ```tsx
- * <XTermWrapper
- *   options={{ mode: 'interactive', wsUrl: 'ws://localhost:3100/terminal' }}
- *   onData={(data) => console.log('User input:', data)}
- *   onReady={(terminal) => console.log('Terminal ready')}
- * />
- * ```
- */
-export function XTermWrapper({
-  options,
-  theme,
-  onData,
-  onReady,
-  onResize,
-  className,
-}: IXTermWrapperProps) {
-  const containerRef = useRef<HTMLDivElement>(null);
-  const terminalRef = useRef<Terminal | null>(null);
-  const fitAddonRef = useRef<FitAddon | null>(null);
-  const searchAddonRef = useRef<SearchAddon | null>(null);
-
-  /**
-   * Handle terminal data input from user.
-   */
-  const handleData = useCallback(
-    (data: string) => {
-      if (options.mode === 'interactive' && onData) {
-        onData(data);
-      }
-    },
-    [options.mode, onData]
-  );
-
-  /**
-   * Initialize xterm.js instance and load addons.
-   *
-   * Note: LigaturesAddon uses `fs` (Node.js module) internally,
-   * so it must be loaded via dynamic import to avoid SSR/bundler
-   * errors. All other addons are browser-safe static imports.
-   */
-  useEffect(() => {
-    if (!containerRef.current) return;
-
-    let disposed = false;
-
-    // Create terminal instance with options
-    const terminal = new Terminal({
-      cursorBlink: options.cursorBlink ?? true,
-      scrollback: options.scrollback ?? 1000,
-      fontSize: options.fontSize ?? 14,
-      fontFamily:
-        options.fontFamily ??
-        "'JetBrains Mono', 'Fira Code', 'SF Mono', 'Monaco', 'Inconsolata', monospace",
-      theme: theme ?? {},
-      convertEol: true,
-      allowProposedApi: true,
-    });
-
-    // Load browser-safe addons (static imports)
-    const fitAddon = new FitAddon();
-    const webLinksAddon = new WebLinksAddon();
-    const searchAddon = new SearchAddon();
-    const unicode11Addon = new Unicode11Addon();
-
-    terminal.loadAddon(fitAddon);
-    terminal.loadAddon(webLinksAddon);
-    terminal.loadAddon(searchAddon);
-    terminal.loadAddon(unicode11Addon);
-
-    // Enable Unicode 11 support
-    terminal.unicode.activeVersion = '11';
-
-    // Open terminal in container
-    terminal.open(containerRef.current);
-    fitAddon.fit();
-
-    // Store references
-    terminalRef.current = terminal;
-    fitAddonRef.current = fitAddon;
-    searchAddonRef.current = searchAddon;
-
-    // Load LigaturesAddon dynamically (requires `fs` — Node.js only at import time)
-    import('@xterm/addon-ligatures').then(({ LigaturesAddon }) => {
-      if (disposed) return;
-      terminal.loadAddon(new LigaturesAddon());
-    }).catch(() => {
-      // Ligatures addon is optional — gracefully degrade if unavailable
-    });
-
-    // Handle data callback
-    if (options.mode === 'interactive') {
-      terminal.onData(handleData);
-    }
-
-    // Notify ready
-    onReady?.(terminal);
-
-    // Cleanup on unmount
-    return () => {
-      disposed = true;
-      terminal.dispose();
-    };
-    // Only run on mount/unmount
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
-
-  /**
-   * Handle window resize with auto-fit.
-   */
-  useEffect(() => {
-    const handleResize = () => {
-      if (!fitAddonRef.current || !terminalRef.current) return;
-
-      const previousDims = { cols: terminalRef.current.cols, rows: terminalRef.current.rows };
-      fitAddonRef.current.fit();
-
-      // Notify parent of resize if dimensions changed
-      if (
-        onResize &&
-        (terminalRef.current.cols !== previousDims.cols ||
-          terminalRef.current.rows !== previousDims.rows)
-      ) {
-        onResize(terminalRef.current.cols, terminalRef.current.rows);
-      }
-    };
-
-    window.addEventListener('resize', handleResize);
-    return () => window.removeEventListener('resize', handleResize);
-  }, [onResize]);
-
-  /**
-   * Handle theme updates.
-   */
-  useEffect(() => {
-    if (!terminalRef.current || !theme) return;
-
-    terminalRef.current.options.theme = theme;
-  }, [theme]);
-
-  /**
-   * Handle data callback updates.
-   */
-  useEffect(() => {
-    if (!terminalRef.current) return;
-
-    // Remove previous listener
-    terminalRef.current.onData(undefined!);
-
-    // Add new listener if interactive mode
-    if (options.mode === 'interactive' && onData) {
-      terminalRef.current.onData(onData);
-    }
-  }, [options.mode, onData]);
-
-  return (
-    <div
-      ref={containerRef}
-      className={className ?? 'xterm-container w-full h-full'}
-      style={{ minHeight: '400px' }}
-      data-terminal-mode={options.mode ?? 'interactive'}
-    />
-  );
-}
-
-/**
- * Export search addon reference for external access.
- *
- * Allows parent components to trigger search in the terminal buffer.
- */
-export function useTerminalSearch(terminalRef: React.RefObject<Terminal | null>) {
-  const search = useCallback((_term: string, _options?: { caseSensitive?: boolean; regex?: boolean }) => {
-    // The search addon needs to be accessed differently
-    // This is a placeholder for future search functionality
-    return false;
-  }, [terminalRef]);
-
-  return { search };
-}

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

@@ -1,163 +0,0 @@
-/**
- * XTerm Adapter - ITerminalAdapter implementation for xterm.js.
- *
- * Wrapper class that adapts xterm.js Terminal to the ITerminalAdapter
- * interface, enabling consistent API across different backends.
- *
- * @module components/devenv/terminal/XTermAdapter
- */
-
-import { Terminal } from '@xterm/xterm';
-import { FitAddon } from '@xterm/addon-fit';
-import type {
-  ITerminalAdapter,
-  ITerminalAdapterCapabilities,
-  ITerminalOptions,
-  ITerminalMode,
-} from './Terminal.types';
-
-/**
- * XTermAdapter implements ITerminalAdapter for xterm.js.
- *
- * Provides xterm.js functionality through the standardized adapter interface.
- * Manages terminal lifecycle including initialization, data writing,
- * resizing, and cleanup.
- */
-export class XTermAdapter implements ITerminalAdapter {
-  /** Backend type identifier */
-  public readonly type = 'xterm' as const;
-
-  /** Adapter capabilities for runtime feature detection */
-  public readonly capabilities: ITerminalAdapterCapabilities = {
-    managesOwnConnection: false,
-    gpuRendering: false,
-    multiPane: false,
-    builtinThemes: false,
-  };
-
-  /** xterm.js Terminal instance */
-  private terminal: Terminal | null = null;
-
-  /** FitAddon for auto-resize */
-  private fitAddon: FitAddon | null = null;
-
-  /** Current options */
-  private options: ITerminalOptions;
-
-  /**
-   * Create XTermAdapter instance.
-   *
-   * @param options - Terminal initialization options
-   */
-  constructor(options: ITerminalOptions) {
-    this.options = options;
-  }
-
-  /**
-   * Initialize the terminal in the given container element.
-   *
-   * Creates xterm.js Terminal instance, loads addons, and opens
-   * in the provided container.
-   *
-   * @param container - DOM element to render terminal into
-   * @param options - Terminal initialization options
-   * @returns Promise that resolves when terminal is ready
-   */
-  async initialize(container: HTMLElement, options: ITerminalOptions): Promise<void> {
-    this.options = options;
-
-    // Create terminal instance
-    this.terminal = new Terminal({
-      cursorBlink: options.cursorBlink ?? true,
-      scrollback: options.scrollback ?? 1000,
-      fontSize: options.fontSize ?? 14,
-      fontFamily:
-        options.fontFamily ??
-        "'JetBrains Mono', 'Fira Code', 'SF Mono', 'Monaco', 'Inconsolata', monospace",
-      theme: options.theme ?? {},
-      convertEol: true,
-    });
-
-    // Load fit addon
-    this.fitAddon = new FitAddon();
-    this.terminal.loadAddon(this.fitAddon);
-
-    // Open terminal
-    this.terminal.open(container);
-    this.fitAddon.fit();
-
-    // Setup data handler for interactive mode
-    if (options.mode === 'interactive' && options.onData) {
-      this.terminal.onData(options.onData);
-    }
-  }
-
-  /**
-   * Write data to the terminal without newline.
-   *
-   * @param data - String data to write
-   */
-  write(data: string): void {
-    this.terminal?.write(data);
-  }
-
-  /**
-   * Write data to the terminal with newline.
-   *
-   * @param data - String data to write
-   */
-  writeln(data: string): void {
-    this.terminal?.writeln(data);
-  }
-
-  /**
-   * Clear the terminal buffer.
-   */
-  clear(): void {
-    this.terminal?.clear();
-  }
-
-  /**
-   * Resize the terminal to the given dimensions.
-   *
-   * @param cols - Number of columns
-   * @param rows - Number of rows
-   */
-  resize(cols: number, rows: number): void {
-    this.terminal?.resize(cols, rows);
-  }
-
-  /**
-   * Dispose of the terminal and release resources.
-   */
-  dispose(): void {
-    this.terminal?.dispose();
-    this.terminal = null;
-    this.fitAddon = null;
-  }
-
-  /**
-   * Switch between interactive and readonly modes.
-   *
-   * @param mode - Target mode
-   */
-  setMode(mode: ITerminalMode): void {
-    // xterm.js doesn't have a built-in readonly mode
-    // We handle this at the component level by not attaching onData handler
-    this.options = { ...this.options, mode };
-  }
-
-  /**
-   * Focus the terminal for input.
-   */
-  focus(): void {
-    this.terminal?.focus();
-  }
-
-  /**
-   * Remove focus from the terminal.
-   */
-  blur(): void {
-    this.terminal?.blur();
-  }
-}