green-screen-react 1.1.2 → 1.2.0

package/README.md

@@ -4,6 +4,8 @@ Multi-protocol legacy terminal React component. Connects to **TN5250** (IBM i /
 
 [**Live Preview**](https://visionbridge-solutions.github.io/green-screen-react/)
 
+> **v1.2.0**: per-field MDT state, `readMdt()` for cheap post-write verification, pluggable session store with `session.lost`/`session.resumed` lifecycle events, lower-level sign-on primitives. See the feature section below. Python integrators can use the new [`green-screen-client`](https://pypi.org/project/green-screen-client/) PyPI package.
+
 ## Install
 
 ```bash
@@ -83,12 +85,64 @@ class MyAdapter implements TerminalAdapter {
   async getStatus() { /* ... */ }
   async sendText(text: string) { /* ... */ }
   async sendKey(key: string) { /* ... */ }
+  async setCursor?(row: number, col: number) { /* ... */ }
+  async readMdt?(modifiedOnly?: boolean) { /* ... */ }  // v1.2.0
   async connect(config?) { /* ... */ }
   async disconnect() { /* ... */ }
   async reconnect() { /* ... */ }
 }
 ```
 
+## v1.2.0 features
+
+### Post-write verification with `readMdt()`
+
+Instead of diffing the entire screen after a batch of writes, ask the proxy which fields actually captured input:
+
+```tsx
+import { WebSocketAdapter } from 'green-screen-react';
+
+const adapter = new WebSocketAdapter({ workerUrl: 'http://localhost:3001' });
+
+// ... after typing into several fields ...
+const modified = await adapter.readMdt();       // only fields with MDT bit set
+const all = await adapter.readMdt(false);       // all input fields
+
+for (const f of modified) {
+  console.log(`row ${f.row} col ${f.col}: "${f.value}"`);
+}
+```
+
+`readMdt` is optional on the `TerminalAdapter` contract — protocols without a per-field modified concept (VT, HP6530) return `[]`.
+
+### Session lifecycle events
+
+`WebSocketAdapter` now exposes hooks for session-level transitions. Use them to prompt reconnect UX or surface a clean "session expired" state without string-matching errors:
+
+```tsx
+const adapter = new WebSocketAdapter({ workerUrl: 'http://localhost:3001' });
+
+adapter.onSessionLost((sessionId, status) => {
+  console.log('lost:', sessionId, status.error);
+  // show "Session expired, click to reconnect" UI
+});
+
+adapter.onSessionResumed((sessionId) => {
+  console.log('reattached:', sessionId);
+});
+```
+
+On page reload, reattach to a session that survived the refresh:
+
+```tsx
+const sessionId = localStorage.getItem('tn5250-session-id');
+if (sessionId) {
+  await adapter.reattach(sessionId);
+}
+```
+
+The proxy keeps the TCP connection alive across WebSocket drops within its idle timeout — `reattach` reconnects the WS and replays the current screen.
+
 ## Props
 
 | Prop | Type | Default | Description |
@@ -106,6 +160,9 @@ class MyAdapter implements TerminalAdapter {
 | `bootLoader` | `ReactNode \| false` | default | Custom boot loader |
 | `onSignIn` | `(config) => void` | - | Sign-in callback |
 | `onScreenChange` | `(screen) => void` | - | Screen change callback |
+| `bootLoaderReady` | `boolean` | - | Explicit boot-loader dismissal (overrides default "dismiss on first screen"). |
+| `headerRight` | `ReactNode` | - | Custom content in the header's right slot. |
+| `statusActions` | `ReactNode` | - | Custom buttons rendered after connection status groups (e.g. disconnect button). |
 | `className` | `string` | - | CSS class |
 | `style` | `CSSProperties` | - | Inline styles |
 

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
-import { ScreenData, ConnectionStatus, ConnectConfig, ProtocolType } from 'green-screen-types';
-export { ConnectConfig, ConnectionStatus, Field, ScreenData, ProtocolType as TerminalProtocol } from 'green-screen-types';
+import { ScreenData, ConnectionStatus, FieldValue, ConnectConfig, ProtocolType } from 'green-screen-types';
+export { ConnectConfig, ConnectionStatus, Field, FieldValue, ScreenData, ProtocolType as TerminalProtocol } from 'green-screen-types';
 
 /**
  * Protocol-specific color/rendering conventions.
@@ -67,6 +67,15 @@ interface TerminalAdapter {
     sendKey(key: string): Promise<SendResult>;
     /** Set cursor position (click-to-position) */
     setCursor?(row: number, col: number): Promise<SendResult>;
+    /**
+     * Read the current values of input fields, optionally restricted to the
+     * ones whose per-field modified-data-tag (MDT) bit is set. Used for cheap
+     * post-write verification: after entering a batch of field values, the
+     * caller can confirm what actually landed without re-reading the entire
+     * screen. Protocols without per-field MDT (VT, HP6530) return an empty
+     * array. Optional — adapters without this capability may omit it.
+     */
+    readMdt?(modifiedOnly?: boolean): Promise<FieldValue[]>;
     /** Establish a connection, optionally with sign-in config */
     connect(config?: ConnectConfig): Promise<SendResult>;
     /** Close the connection */
@@ -112,14 +121,18 @@ interface GreenScreenTerminalProps {
     defaultProtocol?: ProtocolType;
     /** Callback when sign-in form is submitted */
     onSignIn?: (config: ConnectConfig) => void;
-    /** Show "press Enter to continue" hint after auto sign-in (for external adapter flows) */
-    autoSignedIn?: boolean;
     /** Disable auto-focus on the terminal after connecting (default false) */
     autoFocusDisabled?: boolean;
     /** Custom boot loader element, or false to disable */
     bootLoader?: React.ReactNode | false;
+    /** When true, dismiss the boot loader. If provided, overrides the default
+     *  "dismiss when screen data arrives" behavior. Use to keep the boot loader
+     *  visible during sign-in, startup command execution, etc. */
+    bootLoaderReady?: boolean;
     /** Content for the right side of the header */
     headerRight?: React.ReactNode;
+    /** Content rendered after the connection status groups (WiFi+host, Key+username) */
+    statusActions?: React.ReactNode;
     /** Overlay content (e.g. "Extracting..." state) */
     overlay?: React.ReactNode;
     /** Callback for notifications (replaces toast) */
@@ -128,6 +141,8 @@ interface GreenScreenTerminalProps {
     onScreenChange?: (screen: ScreenData) => void;
     /** Callback for minimize action (embedded mode) */
     onMinimize?: () => void;
+    /** Show the keyboard-shortcuts button in the header (default true) */
+    showShortcutsButton?: boolean;
     /** Additional CSS class name */
     className?: string;
     /** Inline styles */
@@ -146,7 +161,7 @@ interface GreenScreenTerminalProps {
  *
  * Supports: TN5250 (IBM i), TN3270 (z/OS), VT (OpenVMS/Pick), HP 6530 (NonStop)
  */
-declare function GreenScreenTerminal({ adapter: externalAdapter, baseUrl, workerUrl, protocol, protocolProfile: customProfile, screenData: externalScreenData, connectionStatus: externalStatus, readOnly, pollInterval, autoReconnect: autoReconnectEnabled, maxReconnectAttempts: maxAttempts, embedded, showHeader, typingAnimation, typingBudgetMs, inlineSignIn, defaultProtocol: signInDefaultProtocol, onSignIn, autoSignedIn, autoFocusDisabled, bootLoader, headerRight, overlay, onNotification, onScreenChange, onMinimize, className, style, }: GreenScreenTerminalProps): react_jsx_runtime.JSX.Element;
+declare function GreenScreenTerminal({ adapter: externalAdapter, baseUrl, workerUrl, protocol, protocolProfile: customProfile, screenData: externalScreenData, connectionStatus: externalStatus, readOnly, pollInterval, autoReconnect: autoReconnectEnabled, maxReconnectAttempts: maxAttempts, embedded, showHeader, typingAnimation, typingBudgetMs, inlineSignIn, defaultProtocol: signInDefaultProtocol, onSignIn, autoFocusDisabled, bootLoader, bootLoaderReady, headerRight, statusActions, overlay, onNotification, onScreenChange, onMinimize, showShortcutsButton, className, style, }: GreenScreenTerminalProps): react_jsx_runtime.JSX.Element;
 
 interface TerminalBootLoaderProps {
     /** Text to display during boot animation */
@@ -230,6 +245,7 @@ declare class RestAdapter implements TerminalAdapter {
     sendText(text: string): Promise<SendResult>;
     sendKey(key: string): Promise<SendResult>;
     setCursor(row: number, col: number): Promise<SendResult>;
+    readMdt(modifiedOnly?: boolean): Promise<FieldValue[]>;
     connect(config?: ConnectConfig): Promise<SendResult>;
     disconnect(): Promise<SendResult>;
     reconnect(): Promise<SendResult>;
@@ -260,9 +276,12 @@ declare class WebSocketAdapter implements TerminalAdapter {
     private status;
     private pendingScreenResolver;
     private pendingConnectResolver;
+    private pendingMdtResolver;
     private connectingPromise;
     private screenListeners;
     private statusListeners;
+    private sessionLostListeners;
+    private sessionResumedListeners;
     private _sessionId;
     constructor(options?: WebSocketAdapterOptions);
     private static detectEnvUrl;
@@ -272,11 +291,22 @@ declare class WebSocketAdapter implements TerminalAdapter {
     onScreen(listener: (screen: ScreenData) => void): () => void;
     /** Subscribe to status changes */
     onStatus(listener: (status: ConnectionStatus) => void): () => void;
+    /**
+     * Subscribe to session-lost notifications. Fires when the proxy detects
+     * that the server-side session has terminated (host TCP drop, idle
+     * timeout, explicit destroy). Integrators use this to prompt a reconnect
+     * or swap to a "session expired" UI without relying on error-string
+     * matching.
+     */
+    onSessionLost(listener: (sessionId: string, status: ConnectionStatus) => void): () => void;
+    /** Subscribe to session-resumed notifications (fires after a successful `reattach`). */
+    onSessionResumed(listener: (sessionId: string) => void): () => void;
     getScreen(): Promise<ScreenData | null>;
     getStatus(): Promise<ConnectionStatus>;
     sendText(text: string): Promise<SendResult>;
     sendKey(key: string): Promise<SendResult>;
     setCursor(row: number, col: number): Promise<SendResult>;
+    readMdt(modifiedOnly?: boolean): Promise<FieldValue[]>;
     connect(config?: ConnectConfig): Promise<SendResult>;
     /**
      * Reattach to an existing proxy session (e.g. after page reload).

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
-import { ScreenData, ConnectionStatus, ConnectConfig, ProtocolType } from 'green-screen-types';
-export { ConnectConfig, ConnectionStatus, Field, ScreenData, ProtocolType as TerminalProtocol } from 'green-screen-types';
+import { ScreenData, ConnectionStatus, FieldValue, ConnectConfig, ProtocolType } from 'green-screen-types';
+export { ConnectConfig, ConnectionStatus, Field, FieldValue, ScreenData, ProtocolType as TerminalProtocol } from 'green-screen-types';
 
 /**
  * Protocol-specific color/rendering conventions.
@@ -67,6 +67,15 @@ interface TerminalAdapter {
     sendKey(key: string): Promise<SendResult>;
     /** Set cursor position (click-to-position) */
     setCursor?(row: number, col: number): Promise<SendResult>;
+    /**
+     * Read the current values of input fields, optionally restricted to the
+     * ones whose per-field modified-data-tag (MDT) bit is set. Used for cheap
+     * post-write verification: after entering a batch of field values, the
+     * caller can confirm what actually landed without re-reading the entire
+     * screen. Protocols without per-field MDT (VT, HP6530) return an empty
+     * array. Optional — adapters without this capability may omit it.
+     */
+    readMdt?(modifiedOnly?: boolean): Promise<FieldValue[]>;
     /** Establish a connection, optionally with sign-in config */
     connect(config?: ConnectConfig): Promise<SendResult>;
     /** Close the connection */
@@ -112,14 +121,18 @@ interface GreenScreenTerminalProps {
     defaultProtocol?: ProtocolType;
     /** Callback when sign-in form is submitted */
     onSignIn?: (config: ConnectConfig) => void;
-    /** Show "press Enter to continue" hint after auto sign-in (for external adapter flows) */
-    autoSignedIn?: boolean;
     /** Disable auto-focus on the terminal after connecting (default false) */
     autoFocusDisabled?: boolean;
     /** Custom boot loader element, or false to disable */
     bootLoader?: React.ReactNode | false;
+    /** When true, dismiss the boot loader. If provided, overrides the default
+     *  "dismiss when screen data arrives" behavior. Use to keep the boot loader
+     *  visible during sign-in, startup command execution, etc. */
+    bootLoaderReady?: boolean;
     /** Content for the right side of the header */
     headerRight?: React.ReactNode;
+    /** Content rendered after the connection status groups (WiFi+host, Key+username) */
+    statusActions?: React.ReactNode;
     /** Overlay content (e.g. "Extracting..." state) */
     overlay?: React.ReactNode;
     /** Callback for notifications (replaces toast) */
@@ -128,6 +141,8 @@ interface GreenScreenTerminalProps {
     onScreenChange?: (screen: ScreenData) => void;
     /** Callback for minimize action (embedded mode) */
     onMinimize?: () => void;
+    /** Show the keyboard-shortcuts button in the header (default true) */
+    showShortcutsButton?: boolean;
     /** Additional CSS class name */
     className?: string;
     /** Inline styles */
@@ -146,7 +161,7 @@ interface GreenScreenTerminalProps {
  *
  * Supports: TN5250 (IBM i), TN3270 (z/OS), VT (OpenVMS/Pick), HP 6530 (NonStop)
  */
-declare function GreenScreenTerminal({ adapter: externalAdapter, baseUrl, workerUrl, protocol, protocolProfile: customProfile, screenData: externalScreenData, connectionStatus: externalStatus, readOnly, pollInterval, autoReconnect: autoReconnectEnabled, maxReconnectAttempts: maxAttempts, embedded, showHeader, typingAnimation, typingBudgetMs, inlineSignIn, defaultProtocol: signInDefaultProtocol, onSignIn, autoSignedIn, autoFocusDisabled, bootLoader, headerRight, overlay, onNotification, onScreenChange, onMinimize, className, style, }: GreenScreenTerminalProps): react_jsx_runtime.JSX.Element;
+declare function GreenScreenTerminal({ adapter: externalAdapter, baseUrl, workerUrl, protocol, protocolProfile: customProfile, screenData: externalScreenData, connectionStatus: externalStatus, readOnly, pollInterval, autoReconnect: autoReconnectEnabled, maxReconnectAttempts: maxAttempts, embedded, showHeader, typingAnimation, typingBudgetMs, inlineSignIn, defaultProtocol: signInDefaultProtocol, onSignIn, autoFocusDisabled, bootLoader, bootLoaderReady, headerRight, statusActions, overlay, onNotification, onScreenChange, onMinimize, showShortcutsButton, className, style, }: GreenScreenTerminalProps): react_jsx_runtime.JSX.Element;
 
 interface TerminalBootLoaderProps {
     /** Text to display during boot animation */
@@ -230,6 +245,7 @@ declare class RestAdapter implements TerminalAdapter {
     sendText(text: string): Promise<SendResult>;
     sendKey(key: string): Promise<SendResult>;
     setCursor(row: number, col: number): Promise<SendResult>;
+    readMdt(modifiedOnly?: boolean): Promise<FieldValue[]>;
     connect(config?: ConnectConfig): Promise<SendResult>;
     disconnect(): Promise<SendResult>;
     reconnect(): Promise<SendResult>;
@@ -260,9 +276,12 @@ declare class WebSocketAdapter implements TerminalAdapter {
     private status;
     private pendingScreenResolver;
     private pendingConnectResolver;
+    private pendingMdtResolver;
     private connectingPromise;
     private screenListeners;
     private statusListeners;
+    private sessionLostListeners;
+    private sessionResumedListeners;
     private _sessionId;
     constructor(options?: WebSocketAdapterOptions);
     private static detectEnvUrl;
@@ -272,11 +291,22 @@ declare class WebSocketAdapter implements TerminalAdapter {
     onScreen(listener: (screen: ScreenData) => void): () => void;
     /** Subscribe to status changes */
     onStatus(listener: (status: ConnectionStatus) => void): () => void;
+    /**
+     * Subscribe to session-lost notifications. Fires when the proxy detects
+     * that the server-side session has terminated (host TCP drop, idle
+     * timeout, explicit destroy). Integrators use this to prompt a reconnect
+     * or swap to a "session expired" UI without relying on error-string
+     * matching.
+     */
+    onSessionLost(listener: (sessionId: string, status: ConnectionStatus) => void): () => void;
+    /** Subscribe to session-resumed notifications (fires after a successful `reattach`). */
+    onSessionResumed(listener: (sessionId: string) => void): () => void;
     getScreen(): Promise<ScreenData | null>;
     getStatus(): Promise<ConnectionStatus>;
     sendText(text: string): Promise<SendResult>;
     sendKey(key: string): Promise<SendResult>;
     setCursor(row: number, col: number): Promise<SendResult>;
+    readMdt(modifiedOnly?: boolean): Promise<FieldValue[]>;
     connect(config?: ConnectConfig): Promise<SendResult>;
     /**
      * Reattach to an existing proxy session (e.g. after page reload).