@mks2508/mks-ui 0.5.7 → 0.6.0

package/src/react-ui/blocks/Terminal/hooks/useTerminalSettings.ts

@@ -1,229 +0,0 @@
-/**
- * Global terminal settings hook with localStorage persistence.
- *
- * Manages renderer, PTY backend, theme, and font size preferences
- * using `useSyncExternalStore` for SSR safety and cross-component sync.
- *
- * @module components/devenv/terminal/hooks/useTerminalSettings
- */
-
-import { useSyncExternalStore, useCallback } from 'react';
-import type { ITerminalRendererType, ITerminalPtyBackendType } from '../Terminal.types';
-
-/**
- * Persisted terminal settings.
- */
-export interface ITerminalSettings {
-  /** Terminal renderer engine (default: 'xterm') */
-  renderer: ITerminalRendererType;
-
-  /** PTY backend type (default: 'nodepty') */
-  ptyBackend: ITerminalPtyBackendType;
-
-  /** Restty built-in theme name (default: 'Synthwave Alpha') */
-  resttyThemeName: string;
-
-  /** Font size in CSS pixels (default: 14) */
-  fontSize: number;
-
-  /** Enable CRT shader effects (scanlines, bloom, vignette) */
-  crtEffect: boolean;
-
-  /** Show debug panel below the terminal */
-  debugPanel: boolean;
-}
-
-/**
- * Return type for the useTerminalSettings hook.
- */
-export interface IUseTerminalSettingsReturn {
-  /** Current settings snapshot */
-  settings: ITerminalSettings;
-
-  /** Switch terminal renderer */
-  setRenderer: (renderer: ITerminalRendererType) => void;
-
-  /** Switch PTY backend */
-  setPtyBackend: (backend: ITerminalPtyBackendType) => void;
-
-  /** Set restty built-in theme by name */
-  setResttyThemeName: (name: string) => void;
-
-  /** Set font size (clamped to 10-24) */
-  setFontSize: (size: number) => void;
-
-  /** Toggle CRT shader effects (scanlines, bloom, vignette) */
-  setCrtEffect: (enabled: boolean) => void;
-
-  /** Toggle debug panel visibility */
-  setDebugPanel: (enabled: boolean) => void;
-
-  /** Reset all settings to defaults */
-  resetToDefaults: () => void;
-}
-
-/** localStorage key for terminal settings */
-const STORAGE_KEY = 'mks-terminal-settings';
-
-/** Min/max font size bounds */
-const MIN_FONT_SIZE = 10;
-const MAX_FONT_SIZE = 24;
-
-/**
- * Default terminal settings.
- */
-const DEFAULT_SETTINGS: ITerminalSettings = {
-  renderer: 'xterm',
-  ptyBackend: 'nodepty',
-  resttyThemeName: 'Synthwave Alpha',
-  fontSize: 14,
-  crtEffect: false,
-  debugPanel: false,
-};
-
-/** Set of subscribed listeners for useSyncExternalStore */
-const listeners = new Set<() => void>();
-
-/** Cached settings snapshot — avoids re-parsing on every subscribe call */
-let cachedSettings: ITerminalSettings | null = null;
-
-/**
- * Notify all subscribers that settings have changed.
- */
-function emitChange(): void {
-  cachedSettings = null;
-  for (const listener of listeners) {
-    listener();
-  }
-}
-
-/**
- * Read current settings from localStorage with fallback to defaults.
- */
-function readSettings(): ITerminalSettings {
-  if (cachedSettings) return cachedSettings;
-
-  try {
-    const raw = localStorage.getItem(STORAGE_KEY);
-    if (!raw) {
-      cachedSettings = DEFAULT_SETTINGS;
-      return DEFAULT_SETTINGS;
-    }
-
-    const parsed = JSON.parse(raw) as Partial<ITerminalSettings>;
-    cachedSettings = {
-      renderer: parsed.renderer === 'restty' ? 'restty' : 'xterm',
-      ptyBackend: parsed.ptyBackend === 'webcontainer' ? 'webcontainer' : 'nodepty',
-      resttyThemeName: typeof parsed.resttyThemeName === 'string' ? parsed.resttyThemeName : DEFAULT_SETTINGS.resttyThemeName,
-      fontSize: typeof parsed.fontSize === 'number'
-        ? Math.min(MAX_FONT_SIZE, Math.max(MIN_FONT_SIZE, parsed.fontSize))
-        : DEFAULT_SETTINGS.fontSize,
-      crtEffect: typeof parsed.crtEffect === 'boolean' ? parsed.crtEffect : DEFAULT_SETTINGS.crtEffect,
-      debugPanel: typeof parsed.debugPanel === 'boolean' ? parsed.debugPanel : DEFAULT_SETTINGS.debugPanel,
-    };
-    return cachedSettings;
-  } catch {
-    cachedSettings = DEFAULT_SETTINGS;
-    return DEFAULT_SETTINGS;
-  }
-}
-
-/**
- * Write settings to localStorage and notify subscribers.
- *
- * @param settings - Settings object to persist
- */
-function writeSettings(settings: ITerminalSettings): void {
-  try {
-    localStorage.setItem(STORAGE_KEY, JSON.stringify(settings));
-  } catch {
-    // localStorage unavailable — settings stay in-memory only
-  }
-  emitChange();
-}
-
-/**
- * Subscribe function for useSyncExternalStore.
- */
-function subscribe(listener: () => void): () => void {
-  listeners.add(listener);
-  return () => listeners.delete(listener);
-}
-
-/**
- * Snapshot function for useSyncExternalStore.
- */
-function getSnapshot(): ITerminalSettings {
-  return readSettings();
-}
-
-/**
- * Server snapshot — returns defaults (SSR-safe).
- */
-function getServerSnapshot(): ITerminalSettings {
-  return DEFAULT_SETTINGS;
-}
-
-/**
- * Hook for reading and mutating global terminal settings.
- *
- * Settings persist to localStorage and sync across all components
- * using `useSyncExternalStore`. SSR-safe via `getServerSnapshot`.
- *
- * @returns Settings state and mutation functions
- *
- * @example
- * ```tsx
- * const { settings, setRenderer, setResttyThemeName } = useTerminalSettings();
- *
- * // Read
- * console.log(settings.renderer); // 'xterm' | 'restty'
- *
- * // Mutate — triggers re-render in all consumers
- * setRenderer('restty');
- * setResttyThemeName('Dracula');
- * ```
- */
-export function useTerminalSettings(): IUseTerminalSettingsReturn {
-  const settings = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
-
-  const setRenderer = useCallback((renderer: ITerminalRendererType) => {
-    writeSettings({ ...readSettings(), renderer });
-  }, []);
-
-  const setPtyBackend = useCallback((ptyBackend: ITerminalPtyBackendType) => {
-    writeSettings({ ...readSettings(), ptyBackend });
-  }, []);
-
-  const setResttyThemeName = useCallback((resttyThemeName: string) => {
-    writeSettings({ ...readSettings(), resttyThemeName });
-  }, []);
-
-  const setFontSize = useCallback((fontSize: number) => {
-    const clamped = Math.min(MAX_FONT_SIZE, Math.max(MIN_FONT_SIZE, fontSize));
-    writeSettings({ ...readSettings(), fontSize: clamped });
-  }, []);
-
-  const setCrtEffect = useCallback((enabled: boolean) => {
-    writeSettings({ ...readSettings(), crtEffect: enabled });
-  }, []);
-
-  const setDebugPanel = useCallback((enabled: boolean) => {
-    writeSettings({ ...readSettings(), debugPanel: enabled });
-  }, []);
-
-  const resetToDefaults = useCallback(() => {
-    writeSettings({ ...DEFAULT_SETTINGS });
-  }, []);
-
-  return {
-    settings,
-    setRenderer,
-    setPtyBackend,
-    setResttyThemeName,
-    setFontSize,
-    setCrtEffect,
-    setDebugPanel,
-    resetToDefaults,
-  };
-}

package/src/react-ui/blocks/Terminal/hooks/useTerminalWebSocket.ts

@@ -1,292 +0,0 @@
-/**
- * useTerminalWebSocket Hook.
- *
- * Manages WebSocket lifecycle for interactive terminal connections.
- * Handles connect, disconnect, auto-reconnect with exponential backoff,
- * and message send/receive for terminal I/O.
- *
- * @module components/devenv/terminal/hooks/useTerminalWebSocket
- */
-
-'use client';
-
-import { useRef, useState, useCallback, useEffect } from 'react';
-
-/**
- * Connection status for terminal WebSocket.
- */
-export type TTerminalWsStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
-
-/**
- * Options for useTerminalWebSocket hook.
- */
-export interface IUseTerminalWebSocketOptions {
-  /** WebSocket URL (ws:// or wss://) */
-  wsUrl: string;
-
-  /** Enable auto-reconnect on disconnect (default: true) */
-  autoReconnect?: boolean;
-
-  /** Maximum reconnect attempts (default: 3) */
-  maxReconnectAttempts?: number;
-
-  /** Base delay for exponential backoff in ms (default: 500) */
-  baseReconnectDelay?: number;
-
-  /** Callback when connection opens */
-  onConnect?: () => void;
-
-  /** Callback when connection closes */
-  onDisconnect?: () => void;
-
-  /** Callback when output data is received */
-  onOutput?: (data: string) => void;
-
-  /** Callback when an error message is received */
-  onError?: (error: string) => void;
-
-  /** Callback when any server message is received */
-  onMessage?: (message: ITerminalWsServerMessage) => void;
-}
-
-/**
- * Return value from useTerminalWebSocket hook.
- */
-export interface IUseTerminalWebSocketReturn {
-  /** Current connection status */
-  status: TTerminalWsStatus;
-
-  /** Send raw input data to server */
-  sendInput: (data: string) => void;
-
-  /** Send resize event to server */
-  sendResize: (cols: number, rows: number) => void;
-
-  /** Send attach to session */
-  sendAttach: (sessionId: string) => void;
-
-  /** Send create session request */
-  sendCreate: (options?: { name?: string; workspaceId?: string; cwd?: string }) => void;
-
-  /** Send kill session request */
-  sendKill: (sessionId: string) => void;
-
-  /** Send detach from current session */
-  sendDetach: () => void;
-
-  /** Manually reconnect */
-  reconnect: () => void;
-
-  /** Manually disconnect */
-  disconnect: () => void;
-}
-
-/**
- * Server → Client message types.
- */
-export interface ITerminalWsServerMessage {
-  type: 'welcome' | 'attached' | 'detached' | 'created' | 'output' | 'error' | 'sessions' | 'killed' | 'resized';
-  sessionId?: string;
-  session?: string;
-  data?: string;
-  error?: string;
-  sessions?: Array<{ id: string; name: string; isActive: boolean }>;
-}
-
-/**
- * Client → Server message types.
- */
-type TTerminalWsClientMessage =
-  | { type: 'attach'; session: string }
-  | { type: 'detach' }
-  | { type: 'create'; name?: string; workspaceId?: string; cwd?: string }
-  | { type: 'input'; data: string }
-  | { type: 'resize'; cols: number; rows: number; session?: string }
-  | { type: 'kill'; session: string }
-  | { type: 'list' };
-
-/**
- * useTerminalWebSocket - WebSocket hook for interactive terminal connections.
- *
- * Manages the full WebSocket lifecycle including connection establishment,
- * reconnection with exponential backoff, and typed message send/receive.
- *
- * @param options - Hook configuration options
- * @returns Connection status and message send functions
- *
- * @example
- * ```tsx
- * const { status, sendInput, sendResize, sendAttach } = useTerminalWebSocket({
- *   wsUrl: 'ws://localhost:3100/terminal/session-1',
- *   onOutput: (data) => terminal.write(data),
- *   onConnect: () => console.log('Connected'),
- * });
- *
- * // Send user input
- * terminal.onData((data) => sendInput(data));
- *
- * // Send resize
- * terminal.onResize(({ cols, rows }) => sendResize(cols, rows));
- * ```
- */
-export function useTerminalWebSocket(options: IUseTerminalWebSocketOptions): IUseTerminalWebSocketReturn {
-  const {
-    wsUrl,
-    autoReconnect = true,
-    maxReconnectAttempts = 3,
-    baseReconnectDelay = 500,
-    onConnect,
-    onDisconnect,
-    onOutput,
-    onError,
-    onMessage,
-  } = options;
-
-  const [status, setStatus] = useState<TTerminalWsStatus>('disconnected');
-  const wsRef = useRef<WebSocket | null>(null);
-  const reconnectAttemptsRef = useRef(0);
-  const reconnectTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const intentionalCloseRef = useRef(false);
-
-  /**
-   * Send a typed message over the WebSocket.
-   */
-  const sendMessage = useCallback((message: TTerminalWsClientMessage) => {
-    if (wsRef.current?.readyState === WebSocket.OPEN) {
-      wsRef.current.send(JSON.stringify(message));
-    }
-  }, []);
-
-  /**
-   * Connect to the WebSocket server.
-   */
-  const connect = useCallback(() => {
-    // Cleanup existing connection
-    if (wsRef.current) {
-      intentionalCloseRef.current = true;
-      wsRef.current.close();
-      wsRef.current = null;
-    }
-
-    intentionalCloseRef.current = false;
-    setStatus('connecting');
-
-    const ws = new WebSocket(wsUrl);
-    wsRef.current = ws;
-
-    ws.onopen = () => {
-      setStatus('connected');
-      reconnectAttemptsRef.current = 0;
-      onConnect?.();
-    };
-
-    ws.onmessage = (event) => {
-      try {
-        const message: ITerminalWsServerMessage = JSON.parse(
-          typeof event.data === 'string' ? event.data : event.data.toString()
-        );
-
-        onMessage?.(message);
-
-        switch (message.type) {
-          case 'output':
-            if (message.data) {
-              onOutput?.(message.data);
-            }
-            break;
-          case 'error':
-            if (message.error) {
-              onError?.(message.error);
-            }
-            break;
-          default:
-            break;
-        }
-      } catch {
-        // Raw text data - treat as output
-        onOutput?.(typeof event.data === 'string' ? event.data : event.data.toString());
-      }
-    };
-
-    ws.onerror = () => {
-      setStatus('error');
-    };
-
-    ws.onclose = () => {
-      wsRef.current = null;
-
-      if (intentionalCloseRef.current) {
-        setStatus('disconnected');
-        onDisconnect?.();
-        return;
-      }
-
-      setStatus('disconnected');
-      onDisconnect?.();
-
-      // Auto-reconnect with exponential backoff
-      if (autoReconnect && reconnectAttemptsRef.current < maxReconnectAttempts) {
-        const delay = baseReconnectDelay * Math.pow(2, reconnectAttemptsRef.current);
-        reconnectAttemptsRef.current += 1;
-
-        reconnectTimerRef.current = setTimeout(() => {
-          connect();
-        }, delay);
-      }
-    };
-  }, [wsUrl, autoReconnect, maxReconnectAttempts, baseReconnectDelay, onConnect, onDisconnect, onOutput, onError, onMessage]);
-
-  /**
-   * Disconnect from the WebSocket server.
-   */
-  const disconnect = useCallback(() => {
-    if (reconnectTimerRef.current) {
-      clearTimeout(reconnectTimerRef.current);
-      reconnectTimerRef.current = null;
-    }
-
-    intentionalCloseRef.current = true;
-    reconnectAttemptsRef.current = maxReconnectAttempts; // Prevent auto-reconnect
-
-    if (wsRef.current) {
-      wsRef.current.close();
-      wsRef.current = null;
-    }
-
-    setStatus('disconnected');
-  }, [maxReconnectAttempts]);
-
-  /**
-   * Manually trigger reconnection.
-   */
-  const reconnect = useCallback(() => {
-    reconnectAttemptsRef.current = 0;
-    connect();
-  }, [connect]);
-
-  // Connect on mount, disconnect on unmount
-  useEffect(() => {
-    connect();
-
-    return () => {
-      if (reconnectTimerRef.current) {
-        clearTimeout(reconnectTimerRef.current);
-      }
-      intentionalCloseRef.current = true;
-      wsRef.current?.close();
-      wsRef.current = null;
-    };
-  }, [connect]);
-
-  return {
-    status,
-    sendInput: useCallback((data: string) => sendMessage({ type: 'input', data }), [sendMessage]),
-    sendResize: useCallback((cols: number, rows: number) => sendMessage({ type: 'resize', cols, rows }), [sendMessage]),
-    sendAttach: useCallback((sessionId: string) => sendMessage({ type: 'attach', session: sessionId }), [sendMessage]),
-    sendCreate: useCallback((opts) => sendMessage({ type: 'create', ...opts }), [sendMessage]),
-    sendKill: useCallback((sessionId: string) => sendMessage({ type: 'kill', session: sessionId }), [sendMessage]),
-    sendDetach: useCallback(() => sendMessage({ type: 'detach' }), [sendMessage]),
-    reconnect,
-    disconnect,
-  };
-}

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

@@ -1,111 +0,0 @@
-/**
- * Terminal Block barrel export.
- *
- * Full-featured terminal UI with xterm.js and restty GPU renderers,
- * log parsing, ANSI handling, multi-session panels, and glassmorphism chrome.
- *
- * NOTE: This module uses xterm.js/restty which are browser-only.
- * Consumers must load this module client-side only (e.g. next/dynamic with { ssr: false }).
- *
- * @module @mks2508/mks-ui/react/blocks/Terminal
- */
-
-// Main component
-export { TerminalPanel, type ITerminalPanelProps } from './TerminalPanel';
-
-// Parsing module
-export * from './parsing';
-
-// React badge and syntax highlighting components
-export * from './components';
-
-// Hooks
-export {
-  useTerminalWebSocket,
-  type IUseTerminalWebSocketOptions,
-  type IUseTerminalWebSocketReturn,
-  type ITerminalWsServerMessage,
-  type TTerminalWsStatus,
-  useTerminalSettings,
-  type ITerminalSettings,
-  type IUseTerminalSettingsReturn,
-} from './hooks';
-
-// Panel components
-export { TerminalLogsPanel } from './panel/TerminalLogsPanel';
-export { TerminalInteractivePanel } from './panel/TerminalInteractivePanel';
-export { TerminalInteractivePanelRestty } from './panel/TerminalInteractivePanelRestty';
-export { TerminalPanelChrome, NOISE_TEXTURE_SVG, terminalScrollStyles } from './panel/TerminalPanelChrome';
-export { TerminalPanelHeader } from './panel/TerminalPanelHeader';
-export { TerminalPanelFooter } from './panel/TerminalPanelFooter';
-export { LogLinesViewer } from './panel/LogLinesViewer';
-
-// Settings UI
-export { TerminalSettingsPopover } from './panel/TerminalSettingsPopover';
-export { TerminalThemeSelector } from './panel/TerminalThemeSelector';
-
-// Restty adapter
-export { ResttyAdapter } from './ResttyAdapter';
-
-// Restty React wrapper
-export { TerminalRestty, type ITerminalResttyProps, type ITerminalResttyRef } from './TerminalRestty';
-
-// Theme
-export { SYNTHWAVE_TERMINAL_THEME, getTerminalTheme } from './Terminal.theme';
-
-// Restty theme bridge
-export {
-  hexToResttyColor,
-  xtermThemeToGhostty,
-  getSynthwaveGhosttyTheme,
-  type IResttyThemeColor,
-  type IResttyGhosttyTheme,
-} from './Terminal.theme.restty';
-
-// Adapters
-export { createTerminalAdapter, createTerminalAdapterForRenderer } from './Terminal.adapter';
-export { XTermAdapter } from './XTermAdapter';
-
-// XTerm wrapper
-export { XTermWrapper, type IXTermWrapperProps, useTerminalSearch } from './TerminalXterm';
-
-// Types
-export type {
-  ITerminalRendererType,
-  ITerminalPtyBackendType,
-  ITerminalBackendType,
-  ITerminalMode,
-  ITerminalConnectionStatus,
-  ITerminalSession,
-  ITerminalOptions,
-  ITerminalTheme,
-  ITerminalAdapter,
-  ITerminalAdapterCapabilities,
-  IPtyTransport,
-  IPtyTransportFactory,
-  IPtyTransportCallbacks,
-  IPtyTransportConnectOptions,
-} from './Terminal.types';
-
-export type { ITerminalPanelChromeProps } from './panel/TerminalPanelChrome.types';
-export type { ITerminalInteractivePanelProps, ITerminalInteractivePanelRef } from './panel/TerminalInteractivePanel.types';
-export type { ITerminalThemeSelectorProps } from './panel/TerminalThemeSelector';
-export type {
-  ITerminalLogsPanelProps,
-  ITerminalLogsPanelRef,
-  ITerminalPanelHeaderProps,
-  ITerminalPanelToolbarProps,
-  ITerminalPanelFooterProps,
-  ILevelFilterButton,
-  TTerminalAction,
-} from './panel/TerminalLogsPanel.types';
-export type { ILogLinesViewerProps } from './panel/LogLinesViewer';
-export type { TLogLevelFilter } from './parsing/LogParser.types';
-
-// TerminalDisplay (lightweight readonly restty terminal)
-export { TerminalDisplay } from './TerminalDisplay';
-export type { ITerminalDisplayProps, ITerminalDisplayRef, TerminalDisplaySlot } from './TerminalDisplay.types';
-export { terminalDisplayStyles, terminalDisplayVariants, type TerminalDisplayVariantProps } from './TerminalDisplay.styles';
-
-// Chrome StyleSlots + CVA variants
-export { terminalChromeStyles, terminalChromeVariants, ACCENT_GRADIENTS, type TerminalChromeSlot, type TerminalChromeVariantProps } from './panel/TerminalPanelChrome.styles';