tinky-termcap 0.1.0

package/lib/index.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * tinky-termcap - Terminal capability detection for Tinky applications.
+ *
+ * This library provides React hooks and utilities for detecting terminal
+ * capabilities such as:
+ * - **Background color** - Detect light/dark themes via OSC 11
+ * - **Terminal name** - Identify the terminal emulator (xterm, kitty, etc.)
+ * - **Kitty keyboard protocol** - Enhanced keyboard input handling
+ * - **modifyOtherKeys** - Key sequence disambiguation (Ctrl+I vs Tab)
+ *
+ * @example Quick start
+ * ```tsx
+ * import { render } from "tinky";
+ * import { TermcapProvider, useTermcap } from "tinky-termcap";
+ *
+ * function App() {
+ *   const { isReady, backgroundColor, terminalName, kittyProtocol } = useTermcap();
+ *
+ *   if (!isReady) {
+ *     return <Text>Detecting terminal capabilities...</Text>;
+ *   }
+ *
+ *   return (
+ *     <Box flexDirection="column">
+ *       <Text>Terminal: {terminalName ?? "Unknown"}</Text>
+ *       <Text>Background: {backgroundColor ?? "Unknown"}</Text>
+ *       <Text>Kitty Protocol: {kittyProtocol ? "Supported" : "Not supported"}</Text>
+ *     </Box>
+ *   );
+ * }
+ *
+ * render(
+ *   <TermcapProvider>
+ *     <App />
+ *   </TermcapProvider>
+ * );
+ * ```
+ *
+ * @example Direct detection (without React)
+ * ```typescript
+ * import { detectTermcap } from "tinky-termcap";
+ *
+ * async function main() {
+ *   process.stdin.setRawMode(true);
+ *   const caps = await detectTermcap(process.stdin, process.stdout, 1000);
+ *
+ *   console.log("Terminal:", caps.terminalName);
+ *   console.log("Background:", caps.backgroundColor);
+ *   console.log("Kitty:", caps.kittyProtocol);
+ *   console.log("modifyOtherKeys:", caps.modifyOtherKeys);
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DETECTION_TIMEOUT = exports.detectTermcap = exports.useTermcap = exports.TermcapProvider = void 0;
+/**
+ * React context provider for terminal capability detection.
+ *
+ * Wrap your application in `TermcapProvider` to enable automatic terminal
+ * capability detection. Child components can then use `useTermcap()` to
+ * access the detected capabilities.
+ *
+ * @see {@link TermcapProviderProps} for configuration options
+ */
+var TermcapContext_js_1 = require("./contexts/TermcapContext.js");
+Object.defineProperty(exports, "TermcapProvider", { enumerable: true, get: function () { return TermcapContext_js_1.TermcapProvider; } });
+/**
+ * React hook for accessing terminal capabilities.
+ *
+ * Must be used within a `TermcapProvider`. Returns a `TermcapInfo` object
+ * containing the detected terminal capabilities.
+ *
+ * @see {@link TermcapInfo} for the shape of returned data
+ */
+var use_termcap_js_1 = require("./hooks/use-termcap.js");
+Object.defineProperty(exports, "useTermcap", { enumerable: true, get: function () { return use_termcap_js_1.useTermcap; } });
+/**
+ * Low-level terminal capability detection function.
+ *
+ * Use this directly when you need capability detection outside of React,
+ * or when you need more control over the detection process.
+ */
+var detect_termcap_js_1 = require("./utils/detect-termcap.js");
+Object.defineProperty(exports, "detectTermcap", { enumerable: true, get: function () { return detect_termcap_js_1.detectTermcap; } });
+/**
+ * Re-export additional types and constants for advanced usage.
+ */
+var detect_termcap_js_2 = require("./utils/detect-termcap.js");
+Object.defineProperty(exports, "DEFAULT_DETECTION_TIMEOUT", { enumerable: true, get: function () { return detect_termcap_js_2.DEFAULT_DETECTION_TIMEOUT; } });

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,mBAAmB;AACnB,OAAO,EACL,eAAe,EACf,UAAU,GAGX,MAAM,qBAAqB,CAAC;AAE7B,8CAA8C;AAC9C,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,EACzB,eAAe,GAChB,MAAM,aAAa,CAAC"}

package/lib/utils/detect-termcap.d.ts

@@ -0,0 +1,328 @@
+/**
+ * @fileoverview Terminal capability detection utilities.
+ *
+ * This module provides functions and types for detecting terminal capabilities
+ * by sending escape sequence queries to the terminal and parsing responses.
+ * It supports detection of:
+ * - Background color (via OSC 11)
+ * - Terminal name/version (via XTVERSION)
+ * - Kitty keyboard protocol support
+ * - modifyOtherKeys mode support
+ *
+ * @example Basic usage with tinky
+ * ```tsx
+ * import { TermcapProvider, useTermcap } from "tinky-termcap";
+ *
+ * function App() {
+ *   const { isReady, backgroundColor, kittyProtocol } = useTermcap();
+ *
+ *   if (!isReady) return <Text>Detecting...</Text>;
+ *
+ *   return (
+ *     <Box>
+ *       <Text>Background: {backgroundColor ?? "unknown"}</Text>
+ *       <Text>Kitty: {kittyProtocol ? "yes" : "no"}</Text>
+ *     </Box>
+ *   );
+ * }
+ *
+ * render(
+ *   <TermcapProvider>
+ *     <App />
+ *   </TermcapProvider>
+ * );
+ * ```
+ *
+ * @example Direct usage without React
+ * ```typescript
+ * import { detectTermcap } from "tinky-termcap";
+ *
+ * async function main() {
+ *   const caps = await detectTermcap(process.stdin, process.stdout, 1000);
+ *   console.log("Terminal capabilities:", caps);
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { ReadStream, WriteStream } from "tinky";
+/**
+ * Detected terminal capabilities information.
+ *
+ * This interface represents the result of terminal capability detection,
+ * containing information about various terminal features and settings.
+ *
+ * @example
+ * ```typescript
+ * import type { TermcapInfo } from "tinky-termcap";
+ *
+ * // Default state before detection
+ * const defaultCaps: TermcapInfo = {
+ *   isReady: false,
+ *   backgroundColor: undefined,
+ *   terminalName: undefined,
+ *   kittyProtocol: false,
+ *   modifyOtherKeys: false,
+ * };
+ *
+ * // After detection completes
+ * const detectedCaps: TermcapInfo = {
+ *   isReady: true,
+ *   backgroundColor: "#1a1a1a",
+ *   terminalName: "xterm(388)",
+ *   kittyProtocol: true,
+ *   modifyOtherKeys: true,
+ * };
+ * ```
+ */
+export interface TermcapInfo {
+    /**
+     * Whether capability detection has completed.
+     *
+     * This is `false` during detection and becomes `true` once detection
+     * finishes (either successfully or via timeout).
+     *
+     * @example
+     * ```tsx
+     * const { isReady } = useTermcap();
+     *
+     * if (!isReady) {
+     *   return <Text>Detecting terminal capabilities...</Text>;
+     * }
+     * ```
+     */
+    isReady: boolean;
+    /**
+     * Terminal background color in `#rrggbb` format.
+     *
+     * Detected via OSC 11 query. Will be `undefined` if:
+     * - The terminal doesn't support OSC 11
+     * - Detection timed out before receiving a response
+     * - Running in a non-TTY environment
+     *
+     * @example Adapting to light/dark themes
+     * ```typescript
+     * function isDarkBackground(color: string | undefined): boolean {
+     *   if (!color) return true; // Assume dark if unknown
+     *
+     *   const hex = color.slice(1);
+     *   const r = parseInt(hex.slice(0, 2), 16);
+     *   const g = parseInt(hex.slice(2, 4), 16);
+     *   const b = parseInt(hex.slice(4, 6), 16);
+     *
+     *   // Calculate relative luminance
+     *   const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+     *   return luminance < 0.5;
+     * }
+     * ```
+     */
+    backgroundColor: string | undefined;
+    /**
+     * Terminal emulator name and version string.
+     *
+     * Detected via XTVERSION query. Format varies by terminal:
+     * - xterm: `"xterm(388)"`
+     * - kitty: `"kitty(0.31.0)"`
+     * - WezTerm: `"WezTerm 20230712-072601-f4abf8fd"`
+     *
+     * Will be `undefined` if the terminal doesn't respond to XTVERSION.
+     *
+     * @example Terminal-specific feature flags
+     * ```typescript
+     * function supportsImageProtocol(terminalName: string | undefined): boolean {
+     *   if (!terminalName) return false;
+     *   return terminalName.includes("kitty") ||
+     *          terminalName.includes("WezTerm") ||
+     *          terminalName.includes("iTerm");
+     * }
+     * ```
+     */
+    terminalName: string | undefined;
+    /**
+     * Whether Kitty keyboard protocol is supported.
+     *
+     * When `true`, the terminal supports the enhanced Kitty keyboard protocol,
+     * which provides:
+     * - Key release events
+     * - Separate modifier key events
+     * - Unicode code points for all keys
+     * - Disambiguation of similar key sequences
+     *
+     * @example Enabling enhanced keyboard handling
+     * ```typescript
+     * import { useTermcap } from "tinky-termcap";
+     *
+     * function useKeyboardMode() {
+     *   const { kittyProtocol } = useTermcap();
+     *
+     *   useEffect(() => {
+     *     if (kittyProtocol) {
+     *       // Enable Kitty keyboard protocol
+     *       process.stdout.write("\x1b[>1u");
+     *       return () => {
+     *         // Disable on cleanup
+     *         process.stdout.write("\x1b[<u");
+     *       };
+     *     }
+     *   }, [kittyProtocol]);
+     * }
+     * ```
+     *
+     * @see https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+     */
+    kittyProtocol: boolean;
+    /**
+     * Whether modifyOtherKeys mode is supported at level 2 or higher.
+     *
+     * When `true`, the terminal can disambiguate key sequences like:
+     * - `Ctrl+I` vs `Tab`
+     * - `Ctrl+M` vs `Enter`
+     * - `Ctrl+[` vs `Escape`
+     *
+     * This enables more precise keyboard handling in terminal applications.
+     *
+     * @example
+     * ```typescript
+     * const { modifyOtherKeys } = useTermcap();
+     *
+     * if (modifyOtherKeys) {
+     *   console.log("Can distinguish Ctrl+I from Tab");
+     * }
+     * ```
+     *
+     * @see https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
+     */
+    modifyOtherKeys: boolean;
+}
+/**
+ * Default timeout for capability detection in milliseconds.
+ *
+ * This value (1000ms) provides a reasonable balance between:
+ * - Allowing enough time for slow terminals to respond
+ * - Not delaying application startup too long if terminal doesn't respond
+ *
+ * @example Custom timeout usage
+ * ```typescript
+ * import { detectTermcap, DEFAULT_DETECTION_TIMEOUT } from "tinky-termcap";
+ *
+ * // Use half the default timeout for faster startup
+ * const caps = await detectTermcap(stdin, stdout, DEFAULT_DETECTION_TIMEOUT / 2);
+ *
+ * // Or use a longer timeout for slow connections
+ * const caps = await detectTermcap(stdin, stdout, DEFAULT_DETECTION_TIMEOUT * 2);
+ * ```
+ */
+export declare const DEFAULT_DETECTION_TIMEOUT = 1000;
+/**
+ * Detect terminal capabilities by querying the terminal.
+ *
+ * This function sends escape sequence queries to the terminal and parses
+ * the responses to determine supported features. It detects:
+ * - **Background color** - via OSC 11 query
+ * - **Terminal name** - via XTVERSION query
+ * - **Kitty protocol** - enhanced keyboard support
+ * - **modifyOtherKeys** - key disambiguation support
+ *
+ * The function uses Device Attributes (DA) as a "sentinel" - when the DA
+ * response is received, detection is considered complete since terminals
+ * always respond to DA queries.
+ *
+ * @param stdin - Input stream to read terminal responses from.
+ *   If not provided or not a TTY, returns default values immediately.
+ * @param stdout - Output stream to write queries to.
+ *   If not provided or not a TTY, returns default values immediately.
+ * @param timeout - Maximum time to wait for responses in milliseconds.
+ *   Defaults to {@link DEFAULT_DETECTION_TIMEOUT} (1000ms).
+ * @returns Promise resolving to detected capabilities.
+ *
+ * @remarks
+ * - This function should typically only be called once at app startup
+ * - The caller is responsible for enabling raw mode before calling
+ * - In non-TTY environments, returns immediately with default values
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { detectTermcap } from "tinky-termcap";
+ *
+ * async function main() {
+ *   // Enable raw mode first (required for reading responses)
+ *   process.stdin.setRawMode(true);
+ *
+ *   const caps = await detectTermcap(
+ *     process.stdin,
+ *     process.stdout,
+ *     1000
+ *   );
+ *
+ *   console.log("Detection complete:");
+ *   console.log("  Background:", caps.backgroundColor ?? "unknown");
+ *   console.log("  Terminal:", caps.terminalName ?? "unknown");
+ *   console.log("  Kitty:", caps.kittyProtocol ? "yes" : "no");
+ *   console.log("  modifyOtherKeys:", caps.modifyOtherKeys ? "yes" : "no");
+ * }
+ * ```
+ *
+ * @example With tinky hooks
+ * ```tsx
+ * import { useStdin, useStdout } from "tinky";
+ * import { detectTermcap } from "tinky-termcap";
+ *
+ * function DetectionComponent() {
+ *   const { stdin, setRawMode } = useStdin();
+ *   const { stdout } = useStdout();
+ *   const [caps, setCaps] = useState<TermcapInfo | null>(null);
+ *
+ *   useEffect(() => {
+ *     setRawMode(true);
+ *     detectTermcap(stdin, stdout, 1000).then(setCaps);
+ *   }, []);
+ *
+ *   if (!caps) return <Text>Detecting...</Text>;
+ *   return <Text>Ready!</Text>;
+ * }
+ * ```
+ *
+ * @example Testing with mock streams
+ * ```typescript
+ * import { EventEmitter } from "events";
+ * import { ReadStream, WriteStream } from "tinky";
+ * import { detectTermcap } from "tinky-termcap";
+ *
+ * // Create mock streams
+ * const mockStdin = new EventEmitter() as ReadStream;
+ * (mockStdin as any).isTTY = true;
+ *
+ * const mockStdout: WriteStream = {
+ *   isTTY: true,
+ *   write(data: string) {
+ *     // Simulate terminal responding to queries
+ *     setTimeout(() => {
+ *       mockStdin.emit("data", Buffer.from("\x1b[?62;c")); // DA response
+ *     }, 10);
+ *     return true;
+ *   },
+ * };
+ *
+ * const caps = await detectTermcap(mockStdin, mockStdout, 100);
+ * ```
+ */
+export declare function detectTermcap(stdin?: ReadStream, stdout?: WriteStream, timeout?: number): Promise<TermcapInfo>;
+/**
+ * Reset module state for testing purposes.
+ *
+ * This function is provided for test isolation. In the current implementation,
+ * there is no module-level state to reset, but this function is maintained
+ * for API compatibility.
+ *
+ * @example
+ * ```typescript
+ * import { resetForTesting } from "tinky-termcap";
+ *
+ * beforeEach(() => {
+ *   resetForTesting();
+ * });
+ * ```
+ *
+ * @internal
+ */
+export declare function resetForTesting(): void;