@mks2508/mks-ui 0.3.1 → 0.4.0

package/dist/react-ui/blocks/Terminal/TerminalPanel.js

@@ -0,0 +1,183 @@
+'use client';
+
+import { TerminalIcon } from "../../icons/lucide-animated/terminal.js";
+import "../../icons/lucide-animated/index.js";
+import { XTermWrapper } from "./TerminalXterm.js";
+import { getTerminalTheme } from "./Terminal.theme.js";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/react-ui/blocks/Terminal/TerminalPanel.tsx
+/**
+* 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
+*/
+/**
+* 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"
+* />
+* ```
+*/
+function TerminalPanel({ backend = "xterm", mode = "interactive", wsUrl, sseUrl, className, title = "Terminal", showToolbar = true, onStatusChange, onData }) {
+	const [status, setStatus] = useState("disconnected");
+	const terminalRef = useRef(null);
+	const wsRef = useRef(null);
+	const eventSourceRef = useRef(null);
+	/**
+	* Update connection status and notify parent.
+	*/
+	const updateStatus = useCallback((newStatus) => {
+		setStatus(newStatus);
+		onStatusChange?.(newStatus);
+	}, [onStatusChange]);
+	/**
+	* Handle terminal data input from user.
+	*/
+	const handleData = useCallback((data) => {
+		onData?.(data);
+		if (mode === "interactive" && wsRef.current?.readyState === WebSocket.OPEN) wsRef.current.send(data);
+	}, [mode, onData]);
+	/**
+	* Handle terminal ready state.
+	*/
+	const handleReady = useCallback((terminal) => {
+		terminalRef.current = terminal;
+		updateStatus("connected");
+		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) => {
+		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) => {
+		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 = () => {
+		switch (status) {
+			case "connected": return "text-success";
+			case "error": return "text-destructive";
+			case "connecting": return "text-warning";
+			default: return "text-muted-foreground";
+		}
+	};
+	return /* @__PURE__ */ jsxs("section", {
+		className,
+		children: [
+			showToolbar && /* @__PURE__ */ jsxs("div", {
+				className: "flex items-center justify-between mb-2 px-2",
+				children: [/* @__PURE__ */ jsxs("div", {
+					className: "flex items-center gap-2",
+					children: [
+						/* @__PURE__ */ jsx(TerminalIcon, { className: "w-4 h-4 text-primary" }),
+						/* @__PURE__ */ jsx("h2", {
+							className: "text-sm font-semibold font-mono text-foreground",
+							children: title
+						}),
+						/* @__PURE__ */ jsx("span", {
+							className: `text-xs font-mono font-medium ${getStatusColor()}`,
+							"data-terminal-status": true,
+							children: status.toUpperCase()
+						})
+					]
+				}), /* @__PURE__ */ jsx("div", { className: "flex items-center gap-1" })]
+			}),
+			/* @__PURE__ */ jsx(XTermWrapper, {
+				options: {
+					backend,
+					mode,
+					wsUrl,
+					sseUrl,
+					onData: handleData,
+					onError: (error) => {
+						console.error("[TerminalPanel] Error:", error);
+						updateStatus("error");
+					}
+				},
+				theme: getTerminalTheme(),
+				onReady: handleReady
+			}),
+			mode === "interactive" && status === "connected" && /* @__PURE__ */ jsxs("div", {
+				className: "mt-2 px-2 flex items-center justify-between text-xs text-muted-foreground font-mono",
+				children: [/* @__PURE__ */ jsx("span", { children: "Ctrl+C to interrupt • Ctrl+D to exit" }), /* @__PURE__ */ jsxs("span", { children: [
+					terminalRef.current?.cols ?? 0,
+					"x",
+					terminalRef.current?.rows ?? 0
+				] })]
+			})
+		]
+	});
+}
+
+//#endregion
+export { TerminalPanel };

package/dist/react-ui/blocks/Terminal/TerminalRestty.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 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
+ */
+import type { Restty } from 'restty';
+import type { ITerminalTheme, IPtyTransportFactory } from './Terminal.types';
+/**
+ * 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 declare const TerminalRestty: import("react").ForwardRefExoticComponent<ITerminalResttyProps & import("react").RefAttributes<ITerminalResttyRef>>;
+//# sourceMappingURL=TerminalRestty.d.ts.map

package/dist/react-ui/blocks/Terminal/TerminalRestty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TerminalRestty.d.ts","sourceRoot":"","sources":["../../../../src/react-ui/blocks/Terminal/TerminalRestty.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAYH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,KAAK,EAAE,cAAc,EAAiB,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAG5F;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,oBAAoB,CAAC;IAE1C,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,cAAc,CAAC;IAEvB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAE3C,6DAA6D;IAC7D,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAEnC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAEhD,kDAAkD;IAClD,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAEvC,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IAEvB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAE1B,yCAAyC;IACzC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAEpC;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,CAAC,YAAY,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAElG,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,yCAAyC;IACzC,SAAS,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAE/B,yCAAyC;IACzC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAElC,gCAAgC;IAChC,KAAK,EAAE,MAAM,IAAI,CAAC;IAElB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,IAAI,CAAC;IAElB,qCAAqC;IACrC,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB,uBAAuB;IACvB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAEpC,wDAAwD;IACxD,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAE7C,gCAAgC;IAChC,cAAc,EAAE,MAAM,OAAO,CAAC;IAE9B,2BAA2B;IAC3B,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAElC,0BAA0B;IAC1B,aAAa,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,cAAc,qHAqL1B,CAAC"}

package/dist/react-ui/blocks/Terminal/TerminalRestty.js

@@ -0,0 +1,185 @@
+'use client';
+
+import { getSynthwaveGhosttyTheme, xtermThemeToGhostty } from "./Terminal.theme.restty.js";
+import { forwardRef, useEffect, useImperativeHandle, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/react-ui/blocks/Terminal/TerminalRestty.tsx
+/**
+* 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
+*/
+/**
+* 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')}
+* />
+* ```
+*/
+const TerminalRestty = forwardRef(({ createPtyTransport, wsUrl, fontSize = 14, theme, resttyThemeName, gpuRenderer = "auto", onReady, onResize, onPtyStatus, onConnect, onDisconnect, onError, onDesktopNotification, className }, ref) => {
+	const containerRef = useRef(null);
+	const resttyRef = useRef(null);
+	const transportRef = useRef(null);
+	const [isInitialized, setIsInitialized] = useState(false);
+	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;
+			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, rows) => {
+							callbacksRef.current.onResize?.(cols, rows);
+						},
+						onPtyStatus: (status) => {
+							callbacksRef.current.onPtyStatus?.(status);
+						}
+					}
+				},
+				fontSources: [{
+					type: "local",
+					matchers: [
+						"jetbrains mono",
+						"fira code",
+						"sf mono",
+						"cascadia code",
+						"meslo"
+					]
+				}],
+				onDesktopNotification: (notification) => {
+					callbacksRef.current.onDesktopNotification?.(notification);
+				},
+				createInitialPane: true,
+				shortcuts: false,
+				defaultContextMenu: true
+			});
+			resttyRef.current = restty;
+			if (resttyThemeName) {
+				const builtinTheme = getBuiltinTheme(resttyThemeName);
+				if (builtinTheme) restty.applyTheme(builtinTheme);
+			} else if (theme) restty.applyTheme(xtermThemeToGhostty(theme));
+			else restty.applyTheme(getSynthwaveGhosttyTheme());
+			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);
+		};
+	}, []);
+	/**
+	* 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) => resttyRef.current?.sendInput(data),
+		clear: () => resttyRef.current?.clearScreen(),
+		focus: () => resttyRef.current?.focus(),
+		blur: () => resttyRef.current?.blur(),
+		setFontSize: (size) => resttyRef.current?.setFontSize(size),
+		resize: (cols, rows) => resttyRef.current?.resize(cols, rows),
+		isPtyConnected: () => resttyRef.current?.isPtyConnected() ?? false,
+		connectPty: (url) => resttyRef.current?.connectPty(url),
+		disconnectPty: () => resttyRef.current?.disconnectPty()
+	}));
+	return /* @__PURE__ */ jsx("div", {
+		ref: containerRef,
+		className,
+		style: {
+			width: "100%",
+			height: "100%",
+			minHeight: "400px"
+		}
+	});
+});
+TerminalRestty.displayName = "TerminalRestty";
+
+//#endregion
+export { TerminalRestty };

package/dist/react-ui/blocks/Terminal/TerminalXterm.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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
+ */
+import { Terminal } from '@xterm/xterm';
+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 declare function XTermWrapper({ options, theme, onData, onReady, onResize, className, }: IXTermWrapperProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Export search addon reference for external access.
+ *
+ * Allows parent components to trigger search in the terminal buffer.
+ */
+export declare function useTerminalSearch(terminalRef: React.RefObject<Terminal | null>): {
+    search: (_term: string, _options?: {
+        caseSensitive?: boolean;
+        regex?: boolean;
+    }) => false;
+};
+//# sourceMappingURL=TerminalXterm.d.ts.map

package/dist/react-ui/blocks/Terminal/TerminalXterm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TerminalXterm.d.ts","sourceRoot":"","sources":["../../../../src/react-ui/blocks/Terminal/TerminalXterm.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAKxC,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,4BAA4B,CAAC;AAEpC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,OAAO,EAAE,gBAAgB,CAAC;IAE1B,6DAA6D;IAC7D,KAAK,CAAC,EAAE,cAAc,CAAC;IAEvB,wDAAwD;IACxD,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAEhC,sDAAsD;IACtD,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;IAEvC,qCAAqC;IACrC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAEhD,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,EAC3B,OAAO,EACP,KAAK,EACL,MAAM,EACN,OAAO,EACP,QAAQ,EACR,SAAS,GACV,EAAE,kBAAkB,2CAmJpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,QAAQ,GAAG,IAAI,CAAC;oBAC1C,MAAM,aAAa;QAAE,aAAa,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;EAOnG"}

package/dist/react-ui/blocks/Terminal/TerminalXterm.js

@@ -0,0 +1,143 @@
+'use client';
+
+import { useCallback, useEffect, useRef } from "react";
+import { jsx } from "react/jsx-runtime";
+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 "@xterm/xterm/css/xterm.css";
+
+//#region src/react-ui/blocks/Terminal/TerminalXterm.tsx
+/**
+* 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
+*/
+/**
+* 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')}
+* />
+* ```
+*/
+function XTermWrapper({ options, theme, onData, onReady, onResize, className }) {
+	const containerRef = useRef(null);
+	const terminalRef = useRef(null);
+	const fitAddonRef = useRef(null);
+	const searchAddonRef = useRef(null);
+	/**
+	* Handle terminal data input from user.
+	*/
+	const handleData = useCallback((data) => {
+		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;
+		const terminal = new Terminal({
+			cursorBlink: options.cursorBlink ?? true,
+			scrollback: options.scrollback ?? 1e3,
+			fontSize: options.fontSize ?? 14,
+			fontFamily: options.fontFamily ?? "'JetBrains Mono', 'Fira Code', 'SF Mono', 'Monaco', 'Inconsolata', monospace",
+			theme: theme ?? {},
+			convertEol: true,
+			allowProposedApi: true
+		});
+		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);
+		terminal.unicode.activeVersion = "11";
+		terminal.open(containerRef.current);
+		fitAddon.fit();
+		terminalRef.current = terminal;
+		fitAddonRef.current = fitAddon;
+		searchAddonRef.current = searchAddon;
+		import("@xterm/addon-ligatures").then(({ LigaturesAddon }) => {
+			if (disposed) return;
+			terminal.loadAddon(new LigaturesAddon());
+		}).catch(() => {});
+		if (options.mode === "interactive") terminal.onData(handleData);
+		onReady?.(terminal);
+		return () => {
+			disposed = true;
+			terminal.dispose();
+		};
+	}, []);
+	/**
+	* 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();
+			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;
+		terminalRef.current.onData(void 0);
+		if (options.mode === "interactive" && onData) terminalRef.current.onData(onData);
+	}, [options.mode, onData]);
+	return /* @__PURE__ */ jsx("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.
+*/
+function useTerminalSearch(terminalRef) {
+	return { search: useCallback((_term, _options) => {
+		return false;
+	}, [terminalRef]) };
+}
+
+//#endregion
+export { XTermWrapper, useTerminalSearch };