green-screen-react 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VisionBridge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# green-screen-react
+
+Multi-protocol legacy terminal React component supporting TN5250, TN3270, VT220, and HP 6530.
+
+## Features
+
+- **Multi-protocol** — TN5250 (IBM i), TN3270 (mainframe), VT220, HP 6530
+- Protocol-specific color conventions and screen dimensions
+- Keyboard input: text, function keys (F1-F24), tab, arrow keys
+- Field-aware rendering with input field underlines
+- Typing animation with correction detection
+- Auto-reconnect with exponential backoff
+- Fully themeable via CSS custom properties
+- Zero runtime dependencies (peer deps: React 18+)
+- Optional inline sign-in form (host, credentials, protocol picker)
+- Pluggable adapter interface for any backend
+
+## Installation
+
+```bash
+npm install green-screen-react
+```
+
+## Quick Start
+
+```tsx
+import { GreenScreenTerminal, RestAdapter } from 'green-screen-react';
+import 'green-screen-react/styles.css';
+
+const adapter = new RestAdapter({
+  baseUrl: 'https://your-server.com/api/terminal',
+  headers: { Authorization: 'Bearer your-token' },
+});
+
+function App() {
+  return <GreenScreenTerminal adapter={adapter} protocol="tn5250" />;
+}
+```
+
+### Switching Protocols
+
+```tsx
+<GreenScreenTerminal adapter={adapter} protocol="tn3270" />
+<GreenScreenTerminal adapter={adapter} protocol="vt" />
+<GreenScreenTerminal adapter={adapter} protocol="hp6530" />
+```
+
+### Inline Sign-In
+
+Enable a built-in connection form that collects host, credentials, and protocol:
+
+```tsx
+<GreenScreenTerminal
+  adapter={adapter}
+  inlineSignIn
+  defaultProtocol="tn5250"
+  onSignIn={(config) => console.log('Connecting to', config.host)}
+/>
+```
+
+The form renders inside the terminal when disconnected. On submit, it calls `adapter.connect(config)` with `{ host, port, protocol, username, password }`.
+
+## Adapter Interface
+
+The terminal communicates with your backend through an adapter. Implement the `TerminalAdapter` interface or use the built-in `RestAdapter`.
+
+```typescript
+interface TerminalAdapter {
+  getScreen(): Promise<ScreenData | null>;
+  getStatus(): Promise<ConnectionStatus>;
+  sendText(text: string): Promise<SendResult>;
+  sendKey(key: string): Promise<SendResult>;
+  connect(config?: ConnectConfig): Promise<SendResult>;
+  disconnect(): Promise<SendResult>;
+  reconnect(): Promise<SendResult>;
+}
+```
+
+### RestAdapter
+
+For HTTP-based backends with these endpoints (relative to `baseUrl`):
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/screen` | Get current screen content |
+| GET | `/status` | Get connection status |
+| POST | `/send-text` | Send text input `{ text }` |
+| POST | `/send-key` | Send special key `{ key }` |
+| POST | `/connect` | Establish connection |
+| POST | `/disconnect` | Close connection |
+| POST | `/reconnect` | Reconnect |
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `adapter` | `TerminalAdapter` | **required** | Backend communication adapter |
+| `protocol` | `'tn5250' \| 'tn3270' \| 'vt' \| 'hp6530'` | `'tn5250'` | Terminal protocol |
+| `protocolProfile` | `ProtocolProfile` | - | Custom protocol profile (overrides `protocol`) |
+| `screenData` | `ScreenData` | - | Direct screen data injection (bypasses polling) |
+| `connectionStatus` | `ConnectionStatus` | - | Direct status injection |
+| `inlineSignIn` | `boolean` | `false` | Show sign-in form when disconnected |
+| `defaultProtocol` | `TerminalProtocol` | `'tn5250'` | Pre-selected protocol in sign-in form |
+| `onSignIn` | `(config) => void` | - | Sign-in submit callback |
+| `readOnly` | `boolean` | `false` | Disable keyboard input |
+| `pollInterval` | `number` | `2000` | Polling interval in ms (0 to disable) |
+| `autoReconnect` | `boolean` | `true` | Auto-reconnect on disconnect |
+| `maxReconnectAttempts` | `number` | `5` | Max reconnect attempts |
+| `embedded` | `boolean` | `false` | Compact embedded mode |
+| `showHeader` | `boolean` | `true` | Show header bar |
+| `typingAnimation` | `boolean` | `true` | Enable typing animation |
+| `bootLoader` | `ReactNode \| false` | default | Custom boot loader or `false` to disable |
+| `headerRight` | `ReactNode` | - | Content for right side of header |
+| `overlay` | `ReactNode` | - | Custom overlay content |
+| `onNotification` | `(msg, type) => void` | - | Notification callback |
+| `onScreenChange` | `(screen) => void` | - | Screen change callback |
+| `className` | `string` | - | Additional CSS class |
+| `style` | `CSSProperties` | - | Inline styles |
+
+## Theming
+
+Override CSS custom properties to customize the look:
+
+```css
+:root {
+  --terminal-green: #10b981;
+  --terminal-white: #FFFFFF;
+  --terminal-blue: #7B93FF;
+  --terminal-bg: #000000;
+  --terminal-card-bg: #0e1422;
+  --terminal-card-border: #1e293b;
+  --terminal-header-bg: #090e1a;
+  --terminal-font: 'JetBrains Mono', 'Courier New', monospace;
+}
+```
+
+## Exports
+
+### Hooks
+
+- `useTerminalConnection(adapter)` — Connection lifecycle
+- `useTerminalScreen(adapter, interval, enabled)` — Screen polling
+- `useTerminalInput(adapter)` — Send text/key operations
+- `useTypingAnimation(content, enabled, budgetMs)` — Typing animation
+
+### Protocol Profiles
+
+- `getProtocolProfile(protocol)` — Get built-in profile by name
+- `tn5250Profile`, `tn3270Profile`, `vtProfile`, `hp6530Profile`
+
+### Utilities
+
+- `positionToRowCol(content, position)` — Convert linear position to row/col
+- `isFieldEntry(prev, next)` — Detect field entry vs screen transition
+- `getRowColorClass(rowIndex, content)` — Row color convention
+- `parseHeaderRow(line)` — Parse header row into colored segments
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,400 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+/**
+ * Supported terminal protocol types.
+ */
+type TerminalProtocol = 'tn5250' | 'tn3270' | 'vt' | 'hp6530';
+/**
+ * Protocol-specific color/rendering conventions.
+ */
+interface ProtocolColorProfile {
+    /** CSS class for a row based on its index and content */
+    getRowColorClass(rowIndex: number, rowContent: string, totalRows: number): string;
+    /** Parse the header row into colored segments, or null for default rendering */
+    parseHeaderRow(line: string): {
+        text: string;
+        colorClass: string;
+    }[] | null;
+}
+/**
+ * Protocol profile — configures terminal behavior per legacy system type.
+ */
+interface ProtocolProfile {
+    /** Protocol identifier */
+    protocol: TerminalProtocol;
+    /** Human-readable name */
+    displayName: string;
+    /** Default terminal dimensions */
+    defaultRows: number;
+    defaultCols: number;
+    /** Color/rendering profile */
+    colors: ProtocolColorProfile;
+    /** Header label shown in terminal chrome */
+    headerLabel: string;
+    /** Boot loader default text */
+    bootText: string;
+}
+/**
+ * Field definition from the terminal data stream.
+ * Describes an input or protected field on the terminal screen.
+ */
+interface Field {
+    /** 0-based row index */
+    row: number;
+    /** 0-based column index */
+    col: number;
+    /** Field length in characters */
+    length: number;
+    /** Whether the field accepts user input */
+    is_input: boolean;
+    /** Whether the field is protected (read-only) */
+    is_protected: boolean;
+    /** Whether the field is displayed with high intensity (bright/white) */
+    is_highlighted?: boolean;
+    /** Whether the field is displayed in reverse video */
+    is_reverse?: boolean;
+}
+/**
+ * Screen data returned by the adapter.
+ * Represents the current state of the terminal screen.
+ */
+interface ScreenData {
+    /** Screen content as newline-separated text (e.g. 24 lines of 80 chars) */
+    content: string;
+    /** 0-based cursor row */
+    cursor_row: number;
+    /** 0-based cursor column */
+    cursor_col: number;
+    /** Number of rows (default 24) */
+    rows?: number;
+    /** Number of columns (default 80) */
+    cols?: number;
+    /** Field definitions on the current screen */
+    fields?: Field[];
+    /** Unique identifier for the current screen state */
+    screen_signature?: string;
+    /** ISO timestamp of when this screen was captured */
+    timestamp?: string;
+}
+/**
+ * Connection status information.
+ */
+interface ConnectionStatus {
+    /** Whether a TCP connection is established */
+    connected: boolean;
+    /** Current connection state */
+    status: 'disconnected' | 'connecting' | 'connected' | 'authenticated' | 'error';
+    /** Terminal protocol in use */
+    protocol?: TerminalProtocol;
+    /** Host address */
+    host?: string;
+    /** Authenticated username */
+    username?: string;
+    /** Error message if status is 'error' */
+    error?: string;
+}
+/**
+ * Result from a send operation (text or key).
+ */
+interface SendResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Updated cursor row after the operation */
+    cursor_row?: number;
+    /** Updated cursor column after the operation */
+    cursor_col?: number;
+    /** Updated screen content after the operation (for key presses that change screens) */
+    content?: string;
+    /** Updated screen signature */
+    screen_signature?: string;
+    /** Error message on failure */
+    error?: string;
+}
+/**
+ * Adapter interface for terminal communication.
+ *
+ * Implement this interface to connect the terminal component to your backend.
+ * The package ships a `RestAdapter` for HTTP-based backends.
+ */
+interface TerminalAdapter {
+    /** Fetch the current screen content */
+    getScreen(): Promise<ScreenData | null>;
+    /** Fetch the current connection status */
+    getStatus(): Promise<ConnectionStatus>;
+    /** Send text input to the terminal */
+    sendText(text: string): Promise<SendResult>;
+    /** Send a special key (ENTER, F1-F24, TAB, etc.) */
+    sendKey(key: string): Promise<SendResult>;
+    /** Establish a connection, optionally with sign-in config */
+    connect(config?: ConnectConfig): Promise<SendResult>;
+    /** Close the connection */
+    disconnect(): Promise<SendResult>;
+    /** Reconnect to the host */
+    reconnect(): Promise<SendResult>;
+}
+/**
+ * Configuration passed from the inline sign-in form to adapter.connect().
+ */
+interface ConnectConfig {
+    /** Target host address */
+    host: string;
+    /** Target port (optional, adapter/server can default per protocol) */
+    port?: number;
+    /** Terminal protocol */
+    protocol: TerminalProtocol;
+    /** Username for authentication */
+    username: string;
+    /** Password for authentication */
+    password: string;
+}
+/** @deprecated Use `TerminalAdapter` instead */
+type TN5250Adapter = TerminalAdapter;
+
+interface GreenScreenTerminalProps {
+    /** Adapter for communicating with the terminal backend */
+    adapter: TerminalAdapter;
+    /** Terminal protocol (determines color conventions, header label, etc.) */
+    protocol?: TerminalProtocol;
+    /** Custom protocol profile (overrides protocol param) */
+    protocolProfile?: ProtocolProfile;
+    /** Direct screen data injection (bypasses polling) */
+    screenData?: ScreenData | null;
+    /** Direct connection status injection */
+    connectionStatus?: ConnectionStatus | null;
+    /** Whether the terminal is read-only (no keyboard input) */
+    readOnly?: boolean;
+    /** Polling interval in ms (0 to disable polling; default 2000) */
+    pollInterval?: number;
+    /** Whether to auto-reconnect on disconnect (default true) */
+    autoReconnect?: boolean;
+    /** Max auto-reconnect attempts (default 5) */
+    maxReconnectAttempts?: number;
+    /** Compact embedded mode */
+    embedded?: boolean;
+    /** Show the header bar (default true) */
+    showHeader?: boolean;
+    /** Enable typing animation (default true) */
+    typingAnimation?: boolean;
+    /** Typing animation budget in ms (default 60) */
+    typingBudgetMs?: number;
+    /** Show inline sign-in form when disconnected (default false) */
+    inlineSignIn?: boolean;
+    /** Default protocol for the sign-in form dropdown (default 'tn5250') */
+    defaultProtocol?: TerminalProtocol;
+    /** Callback when sign-in form is submitted */
+    onSignIn?: (config: ConnectConfig) => void;
+    /** Custom boot loader element, or false to disable */
+    bootLoader?: React.ReactNode | false;
+    /** Content for the right side of the header */
+    headerRight?: React.ReactNode;
+    /** Overlay content (e.g. "Extracting..." state) */
+    overlay?: React.ReactNode;
+    /** Callback for notifications (replaces toast) */
+    onNotification?: (message: string, type: 'info' | 'error') => void;
+    /** Callback when screen content changes */
+    onScreenChange?: (screen: ScreenData) => void;
+    /** Callback for minimize action (embedded mode) */
+    onMinimize?: () => void;
+    /** Additional CSS class name */
+    className?: string;
+    /** Inline styles */
+    style?: React.CSSProperties;
+}
+/** @deprecated Use GreenScreenTerminalProps instead */
+type TN5250TerminalProps = GreenScreenTerminalProps;
+/**
+ * GreenScreenTerminal — Multi-protocol legacy terminal emulator component.
+ *
+ * Renders a terminal screen with:
+ * - Green-on-black terminal aesthetic with protocol-specific color conventions
+ * - Connection status indicator
+ * - Keyboard input support (text, function keys, tab)
+ * - Auto-reconnect with exponential backoff
+ * - Typing animation for field entries
+ * - Focus lock mode for keyboard capture
+ *
+ * Supports: TN5250 (IBM i), TN3270 (z/OS), VT (OpenVMS/Pick), HP 6530 (NonStop)
+ */
+declare function GreenScreenTerminal({ adapter, protocol, protocolProfile: customProfile, screenData: externalScreenData, connectionStatus: externalStatus, readOnly, pollInterval, autoReconnect: autoReconnectEnabled, maxReconnectAttempts: maxAttempts, embedded, showHeader, typingAnimation, typingBudgetMs, inlineSignIn, defaultProtocol: signInDefaultProtocol, onSignIn, bootLoader, headerRight, overlay, onNotification, onScreenChange, onMinimize, className, style, }: GreenScreenTerminalProps): react_jsx_runtime.JSX.Element;
+/** @deprecated Use GreenScreenTerminal instead */
+declare const TN5250Terminal: typeof GreenScreenTerminal;
+
+interface TerminalBootLoaderProps {
+    /** Text to display during boot animation */
+    brandText?: string;
+    /** Speed in ms per character */
+    charSpeed?: number;
+    /** Optional logo element to render alongside the text */
+    logo?: React.ReactNode;
+    /** Height of the boot loader container */
+    height?: number | string;
+}
+/**
+ * Animated boot loader for the terminal.
+ * Shows a typewriter-style text reveal animation.
+ */
+declare function TerminalBootLoader({ brandText, charSpeed, logo, height, }: TerminalBootLoaderProps): react_jsx_runtime.JSX.Element;
+
+interface RestAdapterOptions {
+    /** Base URL for the terminal API (e.g. "https://myhost.com/api/terminal") */
+    baseUrl: string;
+    /** Optional headers to include with every request (e.g. Authorization) */
+    headers?: Record<string, string>;
+    /** Optional function that returns headers (called per-request, useful for dynamic tokens) */
+    getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+}
+/**
+ * REST API adapter for terminal communication.
+ *
+ * Expects a backend that exposes these endpoints relative to `baseUrl`:
+ * - GET  /screen       → ScreenData
+ * - GET  /status       → ConnectionStatus
+ * - POST /send-text    → SendResult  (body: { text })
+ * - POST /send-key     → SendResult  (body: { key })
+ * - POST /connect      → SendResult
+ * - POST /disconnect   → SendResult
+ * - POST /reconnect    → SendResult
+ */
+declare class RestAdapter implements TerminalAdapter {
+    private baseUrl;
+    private staticHeaders;
+    private getHeaders?;
+    constructor(options: RestAdapterOptions);
+    private buildHeaders;
+    private request;
+    getScreen(): Promise<ScreenData | null>;
+    getStatus(): Promise<ConnectionStatus>;
+    sendText(text: string): Promise<SendResult>;
+    sendKey(key: string): Promise<SendResult>;
+    connect(config?: ConnectConfig): Promise<SendResult>;
+    disconnect(): Promise<SendResult>;
+    reconnect(): Promise<SendResult>;
+}
+
+/**
+ * Hook for typing animation effect on terminal screen content.
+ * Reveals characters progressively when screen content changes.
+ * Also provides animated cursor position that follows the typing.
+ *
+ * Uses a queue-based model: incoming content updates are queued when an
+ * animation is in progress, then played sequentially. This prevents
+ * blinks (no mid-animation cancellation) and skips (every field entry
+ * gets its own animation). Queue depth is capped to avoid falling
+ * behind real-time.
+ *
+ * Screen transitions (large changes) always display SYNCHRONOUSLY.
+ */
+declare function useTypingAnimation(content: string | null | undefined, enabled?: boolean, typingBudgetMs?: number): {
+    displayedContent: string;
+    isAnimating: boolean;
+    animatedCursorPos: {
+        row: number;
+        col: number;
+    } | null;
+};
+
+/**
+ * Hook for terminal connection management via adapter.
+ */
+declare function useTerminalConnection(adapter: TerminalAdapter): {
+    status: ConnectionStatus | null;
+    loading: boolean;
+    error: string | null;
+    fetchStatus: () => Promise<ConnectionStatus | null>;
+    connect: (config?: ConnectConfig) => Promise<{
+        success: boolean;
+        cursor_row?: number;
+        cursor_col?: number;
+        content?: string;
+        screen_signature?: string;
+        error?: string;
+    }>;
+    disconnect: () => Promise<{
+        success: boolean;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+    }>;
+    reconnect: () => Promise<{
+        success: boolean;
+        cursor_row?: number;
+        cursor_col?: number;
+        content?: string;
+        screen_signature?: string;
+        error?: string;
+    }>;
+};
+/**
+ * Hook for terminal screen content with polling.
+ */
+declare function useTerminalScreen(adapter: TerminalAdapter, interval?: number, enabled?: boolean): {
+    data: ScreenData | null;
+    error: unknown;
+};
+/**
+ * Hook for terminal operations (sendText, sendKey).
+ */
+declare function useTerminalInput(adapter: TerminalAdapter): {
+    loading: boolean;
+    error: string | null;
+    sendText: (text: string) => Promise<SendResult>;
+    sendKey: (key: string) => Promise<SendResult>;
+};
+/** @deprecated Use `useTerminalConnection` instead */
+declare const useTN5250Connection: typeof useTerminalConnection;
+/** @deprecated Use `useTerminalScreen` instead */
+declare const useTN5250Screen: typeof useTerminalScreen;
+/** @deprecated Use `useTerminalInput` instead */
+declare const useTN5250Terminal: typeof useTerminalInput;
+
+/**
+ * Get a protocol profile by type. Defaults to TN5250 for backward compatibility.
+ */
+declare function getProtocolProfile(protocol?: TerminalProtocol): ProtocolProfile;
+
+declare const tn5250Profile: ProtocolProfile;
+
+declare const tn3270Profile: ProtocolProfile;
+
+declare const vtProfile: ProtocolProfile;
+
+declare const hp6530Profile: ProtocolProfile;
+
+/**
+ * Convert a linear position in screen content to row/col coordinates.
+ * Content is lines of characters separated by newlines.
+ */
+declare function positionToRowCol(content: string, position: number): {
+    row: number;
+    col: number;
+};
+/**
+ * Detect if a content change is a field entry (small, localized change)
+ * vs a screen transition (large, distributed change).
+ *
+ * Field entries: < 50 changed characters within a span of < 100 positions.
+ * Screen transitions: everything else.
+ */
+declare function isFieldEntry(previousContent: string | null | undefined, content: string | null | undefined): boolean;
+
+/**
+ * Get the appropriate CSS class name for a row.
+ * Delegates to the TN5250 protocol profile for backward compatibility.
+ *
+ * For protocol-aware rendering, use `getProtocolProfile(protocol).colors.getRowColorClass()`.
+ */
+declare function getRowColorClass(rowIndex: number, rowContent: string): string;
+/**
+ * Parse the header row into colored segments.
+ * Delegates to the TN5250 protocol profile for backward compatibility.
+ *
+ * For protocol-aware rendering, use `getProtocolProfile(protocol).colors.parseHeaderRow()`.
+ */
+declare function parseHeaderRow(line: string): {
+    text: string;
+    colorClass: string;
+}[] | null;
+
+export { type ConnectConfig, type ConnectionStatus, type Field, GreenScreenTerminal, type GreenScreenTerminalProps, type ProtocolColorProfile, type ProtocolProfile, RestAdapter, type RestAdapterOptions, type ScreenData, type SendResult, type TN5250Adapter, TN5250Terminal, type TN5250TerminalProps, type TerminalAdapter, TerminalBootLoader, type TerminalBootLoaderProps, type TerminalProtocol, getProtocolProfile, getRowColorClass, hp6530Profile, isFieldEntry, parseHeaderRow, positionToRowCol, tn3270Profile, tn5250Profile, useTN5250Connection, useTN5250Screen, useTN5250Terminal, useTerminalConnection, useTerminalInput, useTerminalScreen, useTypingAnimation, vtProfile };