tinky-termcap 0.1.0

package/lib/TermcapContext.js

@@ -0,0 +1,103 @@
+"use strict";
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useTermcap = useTermcap;
+exports.TermcapProvider = TermcapProvider;
+var jsx_runtime_1 = require("react/jsx-runtime");
+var react_1 = require("react");
+var detect_js_1 = require("./detect.js");
+/**
+ * Default termcap info before detection completes.
+ */
+var defaultTermcapInfo = {
+    isReady: false,
+    backgroundColor: undefined,
+    terminalName: undefined,
+    kittyProtocol: false,
+    modifyOtherKeys: false,
+};
+var TermcapContext = (0, react_1.createContext)(undefined);
+/**
+ * Hook to access terminal capability information.
+ *
+ * Must be used within a `TermcapProvider`.
+ *
+ * @returns Terminal capability information
+ * @throws If used outside of TermcapProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { isReady, backgroundColor, kittyProtocol } = useTermcap();
+ *
+ *   if (!isReady) return <Text>Detecting terminal...</Text>;
+ *
+ *   return (
+ *     <Box>
+ *       <Text>Background: {backgroundColor ?? 'unknown'}</Text>
+ *       <Text>Kitty: {kittyProtocol ? 'yes' : 'no'}</Text>
+ *     </Box>
+ *   );
+ * }
+ * ```
+ */
+function useTermcap() {
+    var context = (0, react_1.useContext)(TermcapContext);
+    if (!context) {
+        throw new Error("useTermcap must be used within a TermcapProvider");
+    }
+    return context;
+}
+/**
+ * Provider component that detects and provides terminal capabilities.
+ *
+ * Performs capability detection on mount and provides results to children
+ * via the `useTermcap` hook.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <TermcapProvider>
+ *       <MyTerminalApp />
+ *     </TermcapProvider>
+ *   );
+ * }
+ * ```
+ */
+function TermcapProvider(_a) {
+    var children = _a.children, _b = _a.timeout, timeout = _b === void 0 ? detect_js_1.DEFAULT_DETECTION_TIMEOUT : _b, initialCapabilities = _a.initialCapabilities;
+    var _c = __read((0, react_1.useState)(initialCapabilities !== null && initialCapabilities !== void 0 ? initialCapabilities : defaultTermcapInfo), 2), capabilities = _c[0], setCapabilities = _c[1];
+    (0, react_1.useEffect)(function () {
+        // Skip detection if initial capabilities provided
+        if (initialCapabilities) {
+            return;
+        }
+        var mounted = true;
+        (0, detect_js_1.detectTerminalCapabilities)(timeout).then(function (result) {
+            if (mounted) {
+                setCapabilities(result);
+            }
+        });
+        return function () {
+            mounted = false;
+        };
+    }, [timeout, initialCapabilities]);
+    var value = (0, react_1.useMemo)(function () { return capabilities; }, [capabilities]);
+    return ((0, jsx_runtime_1.jsx)(TermcapContext.Provider, { value: value, children: children }));
+}

package/lib/TermcapContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TermcapContext.js","sourceRoot":"","sources":["../src/TermcapContext.tsx"],"names":[],"mappings":";AAOA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChF,OAAO,EACL,0BAA0B,EAE1B,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AAErB;;GAEG;AACH,MAAM,kBAAkB,GAAgB;IACtC,OAAO,EAAE,KAAK;IACd,eAAe,EAAE,SAAS;IAC1B,YAAY,EAAE,SAAS;IACvB,aAAa,EAAE,KAAK;IACpB,eAAe,EAAE,KAAK;CACvB,CAAC;AAEF,MAAM,cAAc,GAAG,aAAa,CAA0B,SAAS,CAAC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,OAAO,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC;IAC3C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAcD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,QAAQ,EACR,OAAO,GAAG,yBAAyB,EACnC,mBAAmB,GACE;IACrB,MAAM,CAAC,YAAY,EAAE,eAAe,CAAC,GAAG,QAAQ,CAC9C,mBAAmB,IAAI,kBAAkB,CAC1C,CAAC;IAEF,SAAS,CAAC,GAAG,EAAE;QACb,kDAAkD;QAClD,IAAI,mBAAmB,EAAE,CAAC;YACxB,OAAO;QACT,CAAC;QAED,IAAI,OAAO,GAAG,IAAI,CAAC;QAEnB,0BAA0B,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;YAClD,IAAI,OAAO,EAAE,CAAC;gBACZ,eAAe,CAAC,MAAM,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,OAAO,GAAG,EAAE;YACV,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC;IAEnC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,YAAY,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC;IAE1D,OAAO,CACL,KAAC,cAAc,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAA2B,CAC5E,CAAC;AACJ,CAAC"}

package/lib/contexts/TermcapContext.d.ts

@@ -0,0 +1,237 @@
+/**
+ * @fileoverview React context and provider for terminal capability detection.
+ *
+ * This module provides the `TermcapProvider` component, which performs terminal
+ * capability detection on mount and makes the results available to child
+ * components via the `useTermcap` hook.
+ *
+ * @example Basic setup
+ * ```tsx
+ * import { render } from "tinky";
+ * import { TermcapProvider, useTermcap } from "tinky-termcap";
+ *
+ * function App() {
+ *   const { isReady, terminalName } = useTermcap();
+ *
+ *   if (!isReady) {
+ *     return <Text>Detecting terminal...</Text>;
+ *   }
+ *
+ *   return <Text>Running in {terminalName ?? "unknown terminal"}</Text>;
+ * }
+ *
+ * render(
+ *   <TermcapProvider>
+ *     <App />
+ *   </TermcapProvider>
+ * );
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type React from "react";
+import { type TermcapInfo } from "../utils/detect-termcap.js";
+/**
+ * React context for terminal capability information.
+ *
+ * This context provides `TermcapInfo` to descendant components. Use the
+ * `useTermcap` hook instead of accessing this context directly.
+ *
+ * @example Direct context access (not recommended)
+ * ```tsx
+ * import { useContext } from "react";
+ * import { TermcapContext } from "tinky-termcap";
+ *
+ * function MyComponent() {
+ *   const caps = useContext(TermcapContext);
+ *   // Note: caps may be undefined if not within TermcapProvider
+ *   // Use useTermcap() hook instead for automatic error handling
+ * }
+ * ```
+ *
+ * @see {@link useTermcap} - The recommended way to access capabilities
+ */
+export declare const TermcapContext: React.Context<TermcapInfo | undefined>;
+/**
+ * Props for the `TermcapProvider` component.
+ *
+ * @example With all props
+ * ```tsx
+ * <TermcapProvider
+ *   timeout={500}
+ *   initialCapabilities={{
+ *     isReady: true,
+ *     backgroundColor: "#000000",
+ *     terminalName: "test-terminal",
+ *     kittyProtocol: true,
+ *     modifyOtherKeys: false,
+ *   }}
+ * >
+ *   <App />
+ * </TermcapProvider>
+ * ```
+ */
+export interface TermcapProviderProps {
+    /**
+     * Child components that will have access to terminal capabilities
+     * via the `useTermcap` hook.
+     *
+     * @example
+     * ```tsx
+     * <TermcapProvider>
+     *   <Header />
+     *   <MainContent />
+     *   <Footer />
+     * </TermcapProvider>
+     * ```
+     */
+    children: React.ReactNode;
+    /**
+     * Detection timeout in milliseconds.
+     *
+     * The maximum time to wait for terminal responses before returning
+     * with whatever capabilities have been detected. Lower values mean
+     * faster startup but may miss slow-responding features.
+     *
+     * @defaultValue 1000 (1 second)
+     *
+     * @example Fast startup (may miss some features)
+     * ```tsx
+     * <TermcapProvider timeout={200}>
+     *   <App />
+     * </TermcapProvider>
+     * ```
+     *
+     * @example Extended timeout for slow connections
+     * ```tsx
+     * <TermcapProvider timeout={3000}>
+     *   <App />
+     * </TermcapProvider>
+     * ```
+     */
+    timeout?: number;
+    /**
+     * Skip detection and use provided capabilities.
+     *
+     * When provided, the component will not perform any terminal queries
+     * and will immediately use these values. This is primarily useful for:
+     * - Testing components that depend on specific capabilities
+     * - Server-side rendering where detection is not possible
+     * - Programmatic control of capability values
+     *
+     * @example Testing with mock capabilities
+     * ```tsx
+     * import { render } from "@testing-library/react";
+     *
+     * test("renders with Kitty support", () => {
+     *   const { getByText } = render(
+     *     <TermcapProvider
+     *       initialCapabilities={{
+     *         isReady: true,
+     *         backgroundColor: "#1a1a1a",
+     *         terminalName: "kitty(0.31.0)",
+     *         kittyProtocol: true,
+     *         modifyOtherKeys: true,
+     *       }}
+     *     >
+     *       <MyComponent />
+     *     </TermcapProvider>
+     *   );
+     *
+     *   expect(getByText("Kitty: yes")).toBeInTheDocument();
+     * });
+     * ```
+     *
+     * @example Server-side rendering
+     * ```tsx
+     * // On the server, detection is not possible
+     * const ssrCapabilities: TermcapInfo = {
+     *   isReady: true,
+     *   backgroundColor: undefined,
+     *   terminalName: undefined,
+     *   kittyProtocol: false,
+     *   modifyOtherKeys: false,
+     * };
+     *
+     * function SSRApp() {
+     *   return (
+     *     <TermcapProvider initialCapabilities={ssrCapabilities}>
+     *       <App />
+     *     </TermcapProvider>
+     *   );
+     * }
+     * ```
+     */
+    initialCapabilities?: TermcapInfo;
+}
+/**
+ * Provider component that detects and provides terminal capabilities.
+ *
+ * This component performs terminal capability detection on mount and provides
+ * the results to descendant components via the `useTermcap` hook. It integrates
+ * with Tinky's `useStdin` and `useStdout` hooks to access terminal streams.
+ *
+ * ## Lifecycle
+ *
+ * 1. **Mount**: Enables raw mode and sends detection queries to the terminal
+ * 2. **Detection**: Listens for terminal responses and parses capabilities
+ * 3. **Complete**: Either:
+ *    - All responses received (triggered by Device Attributes response)
+ *    - Timeout reached (returns whatever was detected)
+ * 4. **Unmount**: Cleanup (detection may be aborted if still in progress)
+ *
+ * ## Raw Mode
+ *
+ * The provider enables raw mode for detection. After detection completes,
+ * raw mode remains enabled as Tinky applications typically need it. If you
+ * need to manage raw mode differently, use `initialCapabilities` to skip
+ * detection and manage the terminal state yourself.
+ *
+ * @param props - Component props
+ * @returns React element wrapping children with capability context
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { render } from "tinky";
+ * import { TermcapProvider, useTermcap } from "tinky-termcap";
+ *
+ * function App() {
+ *   const caps = useTermcap();
+ *   return <Text>Terminal: {caps.terminalName ?? "Unknown"}</Text>;
+ * }
+ *
+ * render(
+ *   <TermcapProvider>
+ *     <App />
+ *   </TermcapProvider>
+ * );
+ * ```
+ *
+ * @example With custom timeout
+ * ```tsx
+ * <TermcapProvider timeout={500}>
+ *   <App />
+ * </TermcapProvider>
+ * ```
+ *
+ * @example For testing
+ * ```tsx
+ * <TermcapProvider
+ *   initialCapabilities={{
+ *     isReady: true,
+ *     backgroundColor: "#000000",
+ *     terminalName: "test",
+ *     kittyProtocol: true,
+ *     modifyOtherKeys: false,
+ *   }}
+ * >
+ *   <ComponentUnderTest />
+ * </TermcapProvider>
+ * ```
+ *
+ * @see {@link useTermcap} - Hook to access capabilities in child components
+ * @see {@link TermcapProviderProps} - Available props
+ * @see {@link TermcapInfo} - Shape of the provided capabilities
+ */
+export declare function TermcapProvider({ children, timeout, initialCapabilities, }: TermcapProviderProps): React.ReactElement;
+export type { TermcapInfo };

package/lib/contexts/TermcapContext.js

@@ -0,0 +1,157 @@
+"use strict";
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TermcapContext = void 0;
+exports.TermcapProvider = TermcapProvider;
+var jsx_runtime_1 = require("react/jsx-runtime");
+var react_1 = require("react");
+var tinky_1 = require("tinky");
+var detect_termcap_js_1 = require("../utils/detect-termcap.js");
+/**
+ * Default termcap info before detection completes.
+ *
+ * This object is used as the initial state while capability detection
+ * is in progress. Note that `isReady` is `false` to indicate detection
+ * has not yet completed.
+ *
+ * @internal
+ */
+var defaultTermcapInfo = {
+    isReady: false,
+    backgroundColor: undefined,
+    terminalName: undefined,
+    kittyProtocol: false,
+    modifyOtherKeys: false,
+};
+/**
+ * React context for terminal capability information.
+ *
+ * This context provides `TermcapInfo` to descendant components. Use the
+ * `useTermcap` hook instead of accessing this context directly.
+ *
+ * @example Direct context access (not recommended)
+ * ```tsx
+ * import { useContext } from "react";
+ * import { TermcapContext } from "tinky-termcap";
+ *
+ * function MyComponent() {
+ *   const caps = useContext(TermcapContext);
+ *   // Note: caps may be undefined if not within TermcapProvider
+ *   // Use useTermcap() hook instead for automatic error handling
+ * }
+ * ```
+ *
+ * @see {@link useTermcap} - The recommended way to access capabilities
+ */
+exports.TermcapContext = (0, react_1.createContext)(undefined);
+/**
+ * Provider component that detects and provides terminal capabilities.
+ *
+ * This component performs terminal capability detection on mount and provides
+ * the results to descendant components via the `useTermcap` hook. It integrates
+ * with Tinky's `useStdin` and `useStdout` hooks to access terminal streams.
+ *
+ * ## Lifecycle
+ *
+ * 1. **Mount**: Enables raw mode and sends detection queries to the terminal
+ * 2. **Detection**: Listens for terminal responses and parses capabilities
+ * 3. **Complete**: Either:
+ *    - All responses received (triggered by Device Attributes response)
+ *    - Timeout reached (returns whatever was detected)
+ * 4. **Unmount**: Cleanup (detection may be aborted if still in progress)
+ *
+ * ## Raw Mode
+ *
+ * The provider enables raw mode for detection. After detection completes,
+ * raw mode remains enabled as Tinky applications typically need it. If you
+ * need to manage raw mode differently, use `initialCapabilities` to skip
+ * detection and manage the terminal state yourself.
+ *
+ * @param props - Component props
+ * @returns React element wrapping children with capability context
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { render } from "tinky";
+ * import { TermcapProvider, useTermcap } from "tinky-termcap";
+ *
+ * function App() {
+ *   const caps = useTermcap();
+ *   return <Text>Terminal: {caps.terminalName ?? "Unknown"}</Text>;
+ * }
+ *
+ * render(
+ *   <TermcapProvider>
+ *     <App />
+ *   </TermcapProvider>
+ * );
+ * ```
+ *
+ * @example With custom timeout
+ * ```tsx
+ * <TermcapProvider timeout={500}>
+ *   <App />
+ * </TermcapProvider>
+ * ```
+ *
+ * @example For testing
+ * ```tsx
+ * <TermcapProvider
+ *   initialCapabilities={{
+ *     isReady: true,
+ *     backgroundColor: "#000000",
+ *     terminalName: "test",
+ *     kittyProtocol: true,
+ *     modifyOtherKeys: false,
+ *   }}
+ * >
+ *   <ComponentUnderTest />
+ * </TermcapProvider>
+ * ```
+ *
+ * @see {@link useTermcap} - Hook to access capabilities in child components
+ * @see {@link TermcapProviderProps} - Available props
+ * @see {@link TermcapInfo} - Shape of the provided capabilities
+ */
+function TermcapProvider(_a) {
+    var children = _a.children, _b = _a.timeout, timeout = _b === void 0 ? detect_termcap_js_1.DEFAULT_DETECTION_TIMEOUT : _b, initialCapabilities = _a.initialCapabilities;
+    var _c = __read((0, react_1.useState)(initialCapabilities !== null && initialCapabilities !== void 0 ? initialCapabilities : defaultTermcapInfo), 2), capabilities = _c[0], setCapabilities = _c[1];
+    var _d = (0, tinky_1.useStdin)(), stdin = _d.stdin, setRawMode = _d.setRawMode;
+    var stdout = (0, tinky_1.useStdout)().stdout;
+    (0, react_1.useEffect)(function () {
+        // Skip detection if initial capabilities provided
+        if (initialCapabilities) {
+            return;
+        }
+        var mounted = true;
+        // Enable raw mode for detection
+        setRawMode(true);
+        (0, detect_termcap_js_1.detectTermcap)(stdin, stdout, timeout).then(function (result) {
+            if (mounted) {
+                setCapabilities(result);
+                // We don't disable raw mode here as Tinky applications usually need it.
+                // If necessary, the consumer can manage raw mode.
+            }
+        });
+        return function () {
+            mounted = false;
+        };
+    }, [timeout, initialCapabilities, stdin, stdout, setRawMode]);
+    var value = (0, react_1.useMemo)(function () { return capabilities; }, [capabilities]);
+    return ((0, jsx_runtime_1.jsx)(exports.TermcapContext.Provider, { value: value, children: children }));
+}

package/lib/detect.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Detected terminal capabilities.
+ */
+export interface TermcapInfo {
+    /** Whether detection is complete */
+    isReady: boolean;
+    /** Terminal background color in #rrggbb format, or undefined if not detected */
+    backgroundColor: string | undefined;
+    /** Terminal name/version string, or undefined if not detected */
+    terminalName: string | undefined;
+    /** Whether Kitty keyboard protocol is supported */
+    kittyProtocol: boolean;
+    /** Whether modifyOtherKeys mode is supported (level >= 2) */
+    modifyOtherKeys: boolean;
+}
+/**
+ * Default timeout for capability detection (in milliseconds).
+ */
+export declare const DEFAULT_DETECTION_TIMEOUT = 1000;
+/**
+ * Detect terminal capabilities by querying the terminal.
+ *
+ * This sends escape sequences to query terminal features and parses responses.
+ * Should only be called once at app startup.
+ *
+ * @param timeout - Maximum time to wait for responses (default: 1000ms)
+ * @returns Promise resolving to detected capabilities
+ */
+export declare function detectTerminalCapabilities(timeout?: number): Promise<TermcapInfo>;
+/**
+ * For testing purposes only - reset module state.
+ */
+export declare function resetForTesting(): void;

package/lib/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAwBH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,gFAAgF;IAChF,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,iEAAiE;IACjE,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,mDAAmD;IACnD,aAAa,EAAE,OAAO,CAAC;IACvB,6DAA6D;IAC7D,eAAe,EAAE,OAAO,CAAC;CAC1B;AAuBD;;GAEG;AACH,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C;;;;;;;;GAQG;AACH,wBAAsB,0BAA0B,CAC9C,OAAO,GAAE,MAAkC,GAC1C,OAAO,CAAC,WAAW,CAAC,CAqHtB;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}