@mks2508/mks-ui 0.4.0 → 0.5.1

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

@@ -0,0 +1,254 @@
+/**
+ * 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());
+        }
+
+        // Wait for WASM to be ready before writing content.
+        // Restty loads WASM async internally — panes() returns empty until ready.
+        const waitForWasm = () => {
+          if (destroyed) return;
+          const panes = restty.panes();
+          if (panes && panes.length > 0) {
+            // WASM loaded, pane created — safe to write
+            if (contentRef.current) {
+              restty.sendInput(contentRef.current, 'pty');
+            }
+            setIsReady(true);
+            callbacksRef.current.onReady?.(restty);
+          } else {
+            // Not ready yet, retry
+            requestAnimationFrame(waitForWasm);
+          }
+        };
+        requestAnimationFrame(waitForWasm);
+      };
+
+      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';

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/chrome.ts

@@ -0,0 +1,25 @@
+/**
+ * Terminal Chrome — lightweight barrel export.
+ *
+ * Exports only the glassmorphism shell components (no restty, no xterm).
+ * Use `@mks2508/mks-ui/react/blocks/Terminal/chrome` for zero terminal deps.
+ *
+ * @module @mks2508/mks-ui/react/blocks/Terminal/chrome
+ */
+
+// Chrome shell
+export { TerminalPanelChrome, NOISE_TEXTURE_SVG, terminalScrollStyles } from './panel/TerminalPanelChrome';
+export { TerminalPanelHeader } from './panel/TerminalPanelHeader';
+export { TerminalPanelFooter } from './panel/TerminalPanelFooter';
+
+// Chrome styles + variants
+export {
+  terminalChromeStyles,
+  terminalChromeVariants,
+  ACCENT_GRADIENTS,
+  type TerminalChromeSlot,
+  type TerminalChromeVariantProps,
+} from './panel/TerminalPanelChrome.styles';
+
+// Chrome types
+export type { ITerminalPanelChromeProps } from './panel/TerminalPanelChrome.types';

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

@@ -0,0 +1,46 @@
+/**
+ * Terminal Display — lightweight barrel export.
+ *
+ * Exports the readonly TerminalDisplay component + restty wrapper + chrome.
+ * Depends on restty only (not xterm, not shiki, not xterm addons).
+ * Use `@mks2508/mks-ui/react/blocks/Terminal/display` for minimal deps.
+ *
+ * @module @mks2508/mks-ui/react/blocks/Terminal/display
+ */
+
+// TerminalDisplay (readonly restty terminal)
+export { TerminalDisplay } from './TerminalDisplay';
+export {
+  terminalDisplayStyles,
+  terminalDisplayVariants,
+  type TerminalDisplayVariantProps,
+} from './TerminalDisplay.styles';
+export type {
+  ITerminalDisplayProps,
+  ITerminalDisplayRef,
+  TerminalDisplaySlot,
+} from './TerminalDisplay.types';
+
+// Restty React wrapper (for advanced use)
+export { TerminalRestty } from './TerminalRestty';
+export type { ITerminalResttyProps, ITerminalResttyRef } from './TerminalRestty';
+
+// Chrome (re-exported for convenience)
+export { TerminalPanelChrome, NOISE_TEXTURE_SVG, terminalScrollStyles } from './panel/TerminalPanelChrome';
+export type { ITerminalPanelChromeProps } from './panel/TerminalPanelChrome.types';
+export {
+  terminalChromeStyles,
+  terminalChromeVariants,
+  ACCENT_GRADIENTS,
+  type TerminalChromeSlot,
+} from './panel/TerminalPanelChrome.styles';
+
+// Theme utilities (needed for display customization)
+export { SYNTHWAVE_TERMINAL_THEME, getTerminalTheme } from './Terminal.theme';
+export {
+  hexToResttyColor,
+  xtermThemeToGhostty,
+  getSynthwaveGhosttyTheme,
+  type IResttyThemeColor,
+  type IResttyGhosttyTheme,
+} from './Terminal.theme.restty';

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

@@ -101,3 +101,11 @@ export type {
 } 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';

package/src/react-ui/blocks/Terminal/panel/TerminalPanelChrome.styles.ts

@@ -0,0 +1,75 @@
+/**
+ * TerminalPanelChrome style definitions.
+ *
+ * StyleSlots + CVA variants for the Ghostty-inspired glassmorphism shell.
+ * Follows the mks-ui composable pattern: base styles via StyleSlots,
+ * visual variants via CVA, consumer overrides via SlotOverrides.
+ *
+ * @module components/devenv/terminal/panel/chrome/styles
+ */
+
+import { cva, type VariantProps } from 'class-variance-authority';
+import type { StyleSlots } from '@/core/types';
+
+/** Slot names for TerminalPanelChrome sub-regions */
+export type TerminalChromeSlot =
+  | 'root'
+  | 'accentLine'
+  | 'accentGradient'
+  | 'accentShimmer'
+  | 'header'
+  | 'sessionTabs'
+  | 'actionBar'
+  | 'content'
+  | 'footer';
+
+/**
+ * Default style slots for each chrome sub-region.
+ */
+export const terminalChromeStyles: StyleSlots<TerminalChromeSlot> = {
+  root: 'glass-heavy glass-noise rounded-2xl overflow-hidden relative',
+  accentLine: 'absolute top-0 left-0 right-0 h-px z-10 pointer-events-none overflow-hidden',
+  accentGradient: 'h-full w-full',
+  accentShimmer: 'absolute inset-0 bg-gradient-to-r from-transparent via-white/40 to-transparent',
+  header: '',
+  sessionTabs: '',
+  actionBar: '',
+  content: '',
+  footer: '',
+};
+
+/**
+ * Accent line gradient classes per variant.
+ */
+export const ACCENT_GRADIENTS = {
+  default: 'bg-gradient-to-r from-transparent via-primary/70 to-transparent shadow-[0_0_12px_hsla(330,85%,43%,0.5)]',
+  error: 'bg-gradient-to-r from-transparent via-destructive/70 to-transparent shadow-[0_0_12px_hsla(0,72%,51%,0.5)]',
+  minimal: '',
+} as const;
+
+/**
+ * CVA variants for the chrome root element.
+ */
+export const terminalChromeVariants = cva(terminalChromeStyles.root, {
+  variants: {
+    variant: {
+      /** Default: magenta accent line, full glassmorphism */
+      default: '',
+      /** Minimal: no accent line, no noise texture, simpler rounding */
+      minimal: 'rounded-lg',
+      /** Error: red/destructive accent line instead of magenta */
+      error: '',
+    },
+    size: {
+      default: '',
+      compact: 'rounded-xl',
+    },
+  },
+  defaultVariants: {
+    variant: 'default',
+    size: 'default',
+  },
+});
+
+/** Extracted variant props type for consumer use */
+export type TerminalChromeVariantProps = VariantProps<typeof terminalChromeVariants>;

package/src/react-ui/blocks/Terminal/panel/TerminalPanelChrome.tsx

@@ -12,6 +12,7 @@
  * - macOS-style header (TerminalPanelHeader)
  * - Slots for action bar, children (terminal content), and footer
  * - Neon magenta scrollbar styles
+ * - StyleSlots + CVA variants for customization
  *
  * @module components/devenv/terminal/panel/chrome
  */
@@ -19,6 +20,11 @@
 'use client';
 
 import type { ITerminalPanelChromeProps } from './TerminalPanelChrome.types';
+import {
+  terminalChromeStyles,
+  terminalChromeVariants,
+  ACCENT_GRADIENTS,
+} from './TerminalPanelChrome.styles';
 import { TerminalPanelHeader } from './TerminalPanelHeader';
 import { TerminalSessionTabs } from './TerminalSessionTabs';
 import { cn } from '@/react-ui/lib/utils';
@@ -129,16 +135,16 @@ export const terminalScrollStyles = `
  * consistent visual chrome. Used by both TerminalLogsPanel (readonly)
  * and TerminalInteractivePanel (interactive).
  *
+ * Supports StyleSlots for class overrides and CVA variants
+ * for visual presets (default, minimal, error).
+ *
  * @example
  * ```tsx
  * <TerminalPanelChrome
  *   containerName="devenv-agent-backend"
  *   isConnected={true}
- *   sessions={sessions}
- *   activeSessionId="session-1"
- *   onSessionTabClick={(id) => setActiveSession(id)}
- *   onSessionClose={(id) => closeSession(id)}
- *   onNewSession={() => createSession()}
+ *   variant="error"
+ *   slots={{ root: 'max-h-[400px]', content: 'p-2' }}
  *   actionBar={<TerminalFilterTabs ... />}
  *   footer={<TerminalPanelFooter ... />}
  * >
@@ -149,6 +155,8 @@ export const terminalScrollStyles = `
 export function TerminalPanelChrome({
   containerName,
   isConnected,
+  variant = 'default',
+  size = 'default',
   viewMode = 'terminal',
   onViewModeChange,
   sessions,
@@ -165,6 +173,7 @@ export function TerminalPanelChrome({
   onMinimize,
   onMaximize,
   crtEffect,
+  slots,
   className,
 }: ITerminalPanelChromeProps) {
   /** Whether to render session tabs (multi-session mode) */
@@ -172,63 +181,83 @@ export function TerminalPanelChrome({
     (sessions && sessions.length > 0) ||
     (availableContainers && availableContainers.length > 0);
 
+  /** Whether to show the accent line (hidden in minimal variant) */
+  const showAccentLine = variant !== 'minimal';
+
+  /** Accent gradient based on variant */
+  const accentGradient = ACCENT_GRADIENTS[variant ?? 'default'] ?? ACCENT_GRADIENTS.default;
+
   return (
     <div
       className={cn(
-        'glass-heavy glass-noise rounded-2xl overflow-hidden',
-        className
+        terminalChromeVariants({ variant, size }),
+        slots?.root,
+        className,
       )}
     >
       {/* Animated top accent line with shimmer */}
-      <div className="absolute top-0 left-0 right-0 h-px z-10 pointer-events-none overflow-hidden">
-        <div
-          className="h-full w-full bg-gradient-to-r from-transparent via-primary/70 to-transparent shadow-[0_0_12px_hsla(330,85%,43%,0.5)]"
-        />
-        <div
-          className="absolute inset-0 bg-gradient-to-r from-transparent via-white/40 to-transparent"
-          style={{
-            backgroundSize: '200% 100%',
-            animation: 'shimmer-line 4s ease-in-out infinite',
-          }}
-        />
-      </div>
+      {showAccentLine && (
+        <div className={cn(terminalChromeStyles.accentLine, slots?.accentLine)}>
+          <div className={cn(accentGradient, slots?.accentGradient)} />
+          <div
+            className={cn(terminalChromeStyles.accentShimmer, slots?.accentShimmer)}
+            style={{
+              backgroundSize: '200% 100%',
+              animation: 'shimmer-line 4s ease-in-out infinite',
+            }}
+          />
+        </div>
+      )}
 
       {/* Session Tabs */}
       {showSessionTabs && (
-        <TerminalSessionTabs
-          sessions={sessions || []}
-          activeSessionId={activeSessionId || null}
-          onTabClick={(sessionId) => onSessionTabClick?.(sessionId)}
-          onClose={(sessionId) => onSessionClose?.(sessionId)}
-          onNewSession={onNewSession}
-          availableContainers={availableContainers}
-          onAddContainer={onAddContainer}
-        />
+        <div className={cn(slots?.sessionTabs)}>
+          <TerminalSessionTabs
+            sessions={sessions || []}
+            activeSessionId={activeSessionId || null}
+            onTabClick={(sessionId) => onSessionTabClick?.(sessionId)}
+            onClose={(sessionId) => onSessionClose?.(sessionId)}
+            onNewSession={onNewSession}
+            availableContainers={availableContainers}
+            onAddContainer={onAddContainer}
+          />
+        </div>
       )}
 
       {/* Header */}
-      <TerminalPanelHeader
-        containerName={containerName}
-        isConnected={isConnected}
-        viewMode={viewMode}
-        onViewModeChange={onViewModeChange}
-        onClose={onClose}
-        onMinimize={onMinimize}
-        onMaximize={onMaximize}
-      />
+      <div className={cn(slots?.header)}>
+        <TerminalPanelHeader
+          containerName={containerName}
+          isConnected={isConnected}
+          viewMode={viewMode}
+          onViewModeChange={onViewModeChange}
+          onClose={onClose}
+          onMinimize={onMinimize}
+          onMaximize={onMaximize}
+        />
+      </div>
 
       {/* Action Bar Slot */}
-      {actionBar}
+      {actionBar && (
+        <div className={cn(slots?.actionBar)}>
+          {actionBar}
+        </div>
+      )}
 
       {/* Terminal Content - with optional CRT effects */}
       <div className={cn(
-        crtEffect && 'terminal-crt terminal-bloom'
+        crtEffect && 'terminal-crt terminal-bloom',
+        slots?.content,
       )}>
         {children}
       </div>
 
       {/* Footer Slot */}
-      {footer}
+      {footer && (
+        <div className={cn(slots?.footer)}>
+          {footer}
+        </div>
+      )}
 
       {/* Terminal scroll styles */}
       <style>{terminalScrollStyles}</style>