tinky-termcap 0.1.0

package/lib/detect.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DETECTION_TIMEOUT = void 0;
+exports.detectTerminalCapabilities = detectTerminalCapabilities;
+exports.resetForTesting = resetForTesting;
+var fs = __importStar(require("node:fs"));
+// ANSI escape sequence query strings
+var KITTY_QUERY = "\x1b[?u";
+var OSC_11_QUERY = "\x1b]11;?\x1b\\";
+var TERMINAL_NAME_QUERY = "\x1b[>q";
+var DEVICE_ATTRIBUTES_QUERY = "\x1b[c";
+var MODIFY_OTHER_KEYS_QUERY = "\x1b[>4;?m";
+// Response regex patterns
+// eslint-disable-next-line no-control-regex
+var KITTY_REGEX = /\x1b\[\?(\d+)u/;
+// eslint-disable-next-line no-control-regex
+var TERMINAL_NAME_REGEX = /\x1bP>\|(.+?)(\x1b\\|\x07)/;
+// eslint-disable-next-line no-control-regex
+var DEVICE_ATTRIBUTES_REGEX = /\x1b\[\?(\d+)(;\d+)*c/;
+// eslint-disable-next-line no-control-regex
+var OSC_11_REGEX = /\x1b\]11;rgb:([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})(\x1b\\|\x07)?/;
+// eslint-disable-next-line no-control-regex
+var MODIFY_OTHER_KEYS_REGEX = /\x1b\[>4;(\d+)m/;
+/**
+ * Parse RGB color from hex components to #rrggbb format.
+ */
+function parseColor(rHex, gHex, bHex) {
+    var parseComponent = function (hex) {
+        var val = parseInt(hex, 16);
+        if (hex.length === 1)
+            return (val / 15) * 255;
+        if (hex.length === 2)
+            return val;
+        if (hex.length === 3)
+            return (val / 4095) * 255;
+        if (hex.length === 4)
+            return (val / 65535) * 255;
+        return val;
+    };
+    var r = parseComponent(rHex);
+    var g = parseComponent(gHex);
+    var b = parseComponent(bHex);
+    var toHex = function (c) { return Math.round(c).toString(16).padStart(2, "0"); };
+    return "#".concat(toHex(r)).concat(toHex(g)).concat(toHex(b));
+}
+/**
+ * Default timeout for capability detection (in milliseconds).
+ */
+exports.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
+ */
+function detectTerminalCapabilities() {
+    return __awaiter(this, arguments, void 0, function (timeout) {
+        var defaultResult;
+        if (timeout === void 0) { timeout = exports.DEFAULT_DETECTION_TIMEOUT; }
+        return __generator(this, function (_a) {
+            defaultResult = {
+                isReady: true,
+                backgroundColor: undefined,
+                terminalName: undefined,
+                kittyProtocol: false,
+                modifyOtherKeys: false,
+            };
+            // Skip detection if not TTY
+            if (!process.stdin.isTTY || !process.stdout.isTTY) {
+                return [2 /*return*/, defaultResult];
+            }
+            return [2 /*return*/, new Promise(function (resolve) {
+                    var originalRawMode = process.stdin.isRaw;
+                    if (!originalRawMode) {
+                        process.stdin.setRawMode(true);
+                    }
+                    var buffer = "";
+                    var backgroundColor;
+                    var terminalName;
+                    var kittyProtocol = false;
+                    var modifyOtherKeys = false;
+                    var bgReceived = false;
+                    var kittyReceived = false;
+                    var terminalNameReceived = false;
+                    var modifyOtherKeysReceived = false;
+                    var deviceAttributesReceived = false;
+                    var timeoutId;
+                    var cleanup = function () {
+                        if (timeoutId) {
+                            clearTimeout(timeoutId);
+                        }
+                        process.stdin.removeListener("data", onData);
+                        if (!originalRawMode) {
+                            process.stdin.setRawMode(false);
+                        }
+                        resolve({
+                            isReady: true,
+                            backgroundColor: backgroundColor,
+                            terminalName: terminalName,
+                            kittyProtocol: kittyProtocol,
+                            modifyOtherKeys: modifyOtherKeys,
+                        });
+                    };
+                    timeoutId = setTimeout(cleanup, timeout);
+                    var onData = function (data) {
+                        buffer += data.toString();
+                        // Check for background color (OSC 11 response)
+                        if (!bgReceived) {
+                            var match = buffer.match(OSC_11_REGEX);
+                            if (match) {
+                                bgReceived = true;
+                                backgroundColor = parseColor(match[1], match[2], match[3]);
+                            }
+                        }
+                        // Check for Kitty keyboard protocol support
+                        if (!kittyReceived && KITTY_REGEX.test(buffer)) {
+                            kittyReceived = true;
+                            kittyProtocol = true;
+                        }
+                        // Check for modifyOtherKeys support
+                        if (!modifyOtherKeysReceived) {
+                            var match = buffer.match(MODIFY_OTHER_KEYS_REGEX);
+                            if (match) {
+                                modifyOtherKeysReceived = true;
+                                var level = parseInt(match[1], 10);
+                                modifyOtherKeys = level >= 2;
+                            }
+                        }
+                        // Check for terminal name/version
+                        if (!terminalNameReceived) {
+                            var match = buffer.match(TERMINAL_NAME_REGEX);
+                            if (match) {
+                                terminalNameReceived = true;
+                                terminalName = match[1];
+                            }
+                        }
+                        // Device Attributes response acts as sentinel - finish when received
+                        if (!deviceAttributesReceived) {
+                            var match = buffer.match(DEVICE_ATTRIBUTES_REGEX);
+                            if (match) {
+                                deviceAttributesReceived = true;
+                                cleanup();
+                            }
+                        }
+                    };
+                    process.stdin.on("data", onData);
+                    try {
+                        fs.writeSync(process.stdout.fd, KITTY_QUERY +
+                            OSC_11_QUERY +
+                            TERMINAL_NAME_QUERY +
+                            MODIFY_OTHER_KEYS_QUERY +
+                            DEVICE_ATTRIBUTES_QUERY);
+                    }
+                    catch (_a) {
+                        cleanup();
+                    }
+                })];
+        });
+    });
+}
+/**
+ * For testing purposes only - reset module state.
+ */
+function resetForTesting() {
+    // No module-level state to reset in the new design
+}

package/lib/detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"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"}

package/lib/hooks/use-termcap.d.ts

@@ -0,0 +1,151 @@
+/**
+ * @fileoverview React hook for accessing terminal capability information.
+ *
+ * This module provides the `useTermcap` hook, which is the primary way to
+ * access detected terminal capabilities in React components.
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { TermcapProvider, useTermcap } from "tinky-termcap";
+ *
+ * function TerminalInfo() {
+ *   const { isReady, backgroundColor, terminalName } = useTermcap();
+ *
+ *   if (!isReady) {
+ *     return <Text>Detecting terminal capabilities...</Text>;
+ *   }
+ *
+ *   return (
+ *     <Box flexDirection="column">
+ *       <Text>Terminal: {terminalName ?? "Unknown"}</Text>
+ *       <Text>Background: {backgroundColor ?? "Unknown"}</Text>
+ *     </Box>
+ *   );
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <TermcapProvider>
+ *       <TerminalInfo />
+ *     </TermcapProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { type TermcapInfo } from "../utils/detect-termcap.js";
+/**
+ * React hook to access terminal capability information.
+ *
+ * This hook provides access to the `TermcapInfo` object containing
+ * detected terminal capabilities. It must be used within a component
+ * that is a descendant of `TermcapProvider`.
+ *
+ * @returns The current terminal capability information.
+ *
+ * @throws Error if used outside of a `TermcapProvider`. The error message
+ *   will be: "useTermcap must be used within a TermcapProvider"
+ *
+ * @remarks
+ * - The returned `TermcapInfo.isReady` will be `false` until detection completes
+ * - Detection typically takes less than 100ms, but may take up to the timeout value
+ * - In non-TTY environments (CI, piped input), detection returns immediately with defaults
+ *
+ * @example Basic usage with loading state
+ * ```tsx
+ * import { useTermcap } from "tinky-termcap";
+ *
+ * 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>
+ *   );
+ * }
+ * ```
+ *
+ * @example Adapting UI based on terminal theme
+ * ```tsx
+ * import { useTermcap } from "tinky-termcap";
+ *
+ * function ThemedText({ children }: { children: string }) {
+ *   const { backgroundColor } = useTermcap();
+ *
+ *   // Determine if terminal has dark background
+ *   const isDark = useMemo(() => {
+ *     if (!backgroundColor) return true; // Assume dark if unknown
+ *
+ *     const hex = backgroundColor.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);
+ *     const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+ *
+ *     return luminance < 0.5;
+ *   }, [backgroundColor]);
+ *
+ *   return (
+ *     <Text color={isDark ? "white" : "black"}>
+ *       {children}
+ *     </Text>
+ *   );
+ * }
+ * ```
+ *
+ * @example Conditional keyboard handling
+ * ```tsx
+ * import { useTermcap } from "tinky-termcap";
+ * import { useInput } from "tinky";
+ *
+ * function KeyHandler() {
+ *   const { kittyProtocol, modifyOtherKeys } = useTermcap();
+ *
+ *   useInput((input, key) => {
+ *     if (kittyProtocol || modifyOtherKeys) {
+ *       // Enhanced keyboard handling available
+ *       // Can distinguish Ctrl+I from Tab, etc.
+ *     } else {
+ *       // Fall back to basic handling
+ *     }
+ *   });
+ *
+ *   return <Text>Press any key...</Text>;
+ * }
+ * ```
+ *
+ * @example Terminal-specific features
+ * ```tsx
+ * import { useTermcap } from "tinky-termcap";
+ *
+ * function ImageViewer({ imagePath }: { imagePath: string }) {
+ *   const { terminalName, kittyProtocol } = useTermcap();
+ *
+ *   const supportsImages = useMemo(() => {
+ *     if (!terminalName) return false;
+ *     return (
+ *       terminalName.includes("kitty") ||
+ *       terminalName.includes("WezTerm") ||
+ *       terminalName.includes("iTerm")
+ *     );
+ *   }, [terminalName]);
+ *
+ *   if (!supportsImages) {
+ *     return <Text>Image viewing not supported in this terminal</Text>;
+ *   }
+ *
+ *   return <KittyImage src={imagePath} />;
+ * }
+ * ```
+ *
+ * @see {@link TermcapProvider} - The provider component that must wrap components using this hook
+ * @see {@link TermcapInfo} - The type definition for the returned capabilities object
+ */
+export declare function useTermcap(): TermcapInfo;

package/lib/hooks/use-termcap.js

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * @fileoverview React hook for accessing terminal capability information.
+ *
+ * This module provides the `useTermcap` hook, which is the primary way to
+ * access detected terminal capabilities in React components.
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { TermcapProvider, useTermcap } from "tinky-termcap";
+ *
+ * function TerminalInfo() {
+ *   const { isReady, backgroundColor, terminalName } = useTermcap();
+ *
+ *   if (!isReady) {
+ *     return <Text>Detecting terminal capabilities...</Text>;
+ *   }
+ *
+ *   return (
+ *     <Box flexDirection="column">
+ *       <Text>Terminal: {terminalName ?? "Unknown"}</Text>
+ *       <Text>Background: {backgroundColor ?? "Unknown"}</Text>
+ *     </Box>
+ *   );
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <TermcapProvider>
+ *       <TerminalInfo />
+ *     </TermcapProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useTermcap = useTermcap;
+var react_1 = require("react");
+var TermcapContext_js_1 = require("../contexts/TermcapContext.js");
+/**
+ * React hook to access terminal capability information.
+ *
+ * This hook provides access to the `TermcapInfo` object containing
+ * detected terminal capabilities. It must be used within a component
+ * that is a descendant of `TermcapProvider`.
+ *
+ * @returns The current terminal capability information.
+ *
+ * @throws Error if used outside of a `TermcapProvider`. The error message
+ *   will be: "useTermcap must be used within a TermcapProvider"
+ *
+ * @remarks
+ * - The returned `TermcapInfo.isReady` will be `false` until detection completes
+ * - Detection typically takes less than 100ms, but may take up to the timeout value
+ * - In non-TTY environments (CI, piped input), detection returns immediately with defaults
+ *
+ * @example Basic usage with loading state
+ * ```tsx
+ * import { useTermcap } from "tinky-termcap";
+ *
+ * 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>
+ *   );
+ * }
+ * ```
+ *
+ * @example Adapting UI based on terminal theme
+ * ```tsx
+ * import { useTermcap } from "tinky-termcap";
+ *
+ * function ThemedText({ children }: { children: string }) {
+ *   const { backgroundColor } = useTermcap();
+ *
+ *   // Determine if terminal has dark background
+ *   const isDark = useMemo(() => {
+ *     if (!backgroundColor) return true; // Assume dark if unknown
+ *
+ *     const hex = backgroundColor.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);
+ *     const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+ *
+ *     return luminance < 0.5;
+ *   }, [backgroundColor]);
+ *
+ *   return (
+ *     <Text color={isDark ? "white" : "black"}>
+ *       {children}
+ *     </Text>
+ *   );
+ * }
+ * ```
+ *
+ * @example Conditional keyboard handling
+ * ```tsx
+ * import { useTermcap } from "tinky-termcap";
+ * import { useInput } from "tinky";
+ *
+ * function KeyHandler() {
+ *   const { kittyProtocol, modifyOtherKeys } = useTermcap();
+ *
+ *   useInput((input, key) => {
+ *     if (kittyProtocol || modifyOtherKeys) {
+ *       // Enhanced keyboard handling available
+ *       // Can distinguish Ctrl+I from Tab, etc.
+ *     } else {
+ *       // Fall back to basic handling
+ *     }
+ *   });
+ *
+ *   return <Text>Press any key...</Text>;
+ * }
+ * ```
+ *
+ * @example Terminal-specific features
+ * ```tsx
+ * import { useTermcap } from "tinky-termcap";
+ *
+ * function ImageViewer({ imagePath }: { imagePath: string }) {
+ *   const { terminalName, kittyProtocol } = useTermcap();
+ *
+ *   const supportsImages = useMemo(() => {
+ *     if (!terminalName) return false;
+ *     return (
+ *       terminalName.includes("kitty") ||
+ *       terminalName.includes("WezTerm") ||
+ *       terminalName.includes("iTerm")
+ *     );
+ *   }, [terminalName]);
+ *
+ *   if (!supportsImages) {
+ *     return <Text>Image viewing not supported in this terminal</Text>;
+ *   }
+ *
+ *   return <KittyImage src={imagePath} />;
+ * }
+ * ```
+ *
+ * @see {@link TermcapProvider} - The provider component that must wrap components using this hook
+ * @see {@link TermcapInfo} - The type definition for the returned capabilities object
+ */
+function useTermcap() {
+    var context = (0, react_1.useContext)(TermcapContext_js_1.TermcapContext);
+    if (!context) {
+        throw new Error("useTermcap must be used within a TermcapProvider");
+    }
+    return context;
+}

package/lib/index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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
+ */
+/**
+ * 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
+ */
+export { TermcapProvider, type TermcapInfo, type TermcapProviderProps, } from "./contexts/TermcapContext.js";
+/**
+ * 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
+ */
+export { useTermcap } from "./hooks/use-termcap.js";
+/**
+ * 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.
+ */
+export { detectTermcap } from "./utils/detect-termcap.js";
+/**
+ * Re-export additional types and constants for advanced usage.
+ */
+export { DEFAULT_DETECTION_TIMEOUT } from "./utils/detect-termcap.js";

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,eAAe,EACf,UAAU,EACV,KAAK,WAAW,EAChB,KAAK,oBAAoB,GAC1B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,EACzB,eAAe,GAChB,MAAM,aAAa,CAAC"}