tinky-termcap 0.1.0

package/lib/utils/term-features.d.ts

@@ -0,0 +1,242 @@
+/**
+ * @fileoverview Terminal feature query definitions for capability detection.
+ *
+ * This module defines the query sequences and response patterns for detecting
+ * various terminal capabilities. Each feature is represented as a `TermFeature`
+ * object containing the ANSI escape sequence to query the feature and a regex
+ * pattern to match the terminal's response.
+ *
+ * @example
+ * ```typescript
+ * import { KittyFeature, Osc11Feature } from "tinky-termcap/utils/term-features";
+ *
+ * // Send query to terminal
+ * process.stdout.write(KittyFeature.query);
+ *
+ * // Parse response
+ * const response = "\\x1b[?1u";
+ * if (KittyFeature.responseRegex.test(response)) {
+ *   console.log("Kitty keyboard protocol is supported!");
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * Interface for terminal feature query definitions.
+ *
+ * A `TermFeature` encapsulates the information needed to detect a specific
+ * terminal capability:
+ * - The ANSI escape sequence query to send to the terminal
+ * - A regex pattern to match and parse the terminal's response
+ *
+ * @example Creating a custom feature detector
+ * ```typescript
+ * import type { TermFeature } from "tinky-termcap";
+ *
+ * // Define a custom feature to detect sixel graphics support
+ * const SixelFeature: TermFeature = {
+ *   query: "\x1b[c",  // Request device attributes
+ *   responseRegex: /\x1b\[\?[\d;]*4[\d;]*c/,  // Check for "4" in response
+ * };
+ * ```
+ *
+ * @see {@link KittyFeature} for Kitty keyboard protocol detection
+ * @see {@link Osc11Feature} for background color detection
+ * @see {@link TerminalNameFeature} for terminal name detection
+ * @see {@link DeviceAttributesFeature} for device attributes detection
+ * @see {@link ModifyOtherKeysFeature} for modifyOtherKeys support detection
+ */
+export interface TermFeature {
+    /**
+     * ANSI escape sequence query string to send to the terminal.
+     *
+     * This sequence requests information from the terminal. The terminal
+     * will respond with data matching the `responseRegex` pattern if the
+     * feature is supported.
+     *
+     * @example
+     * ```typescript
+     * // Send the query to stdout
+     * process.stdout.write(feature.query);
+     * ```
+     */
+    query: string;
+    /**
+     * Regular expression pattern to match the terminal's response.
+     *
+     * The regex may contain capture groups to extract specific values
+     * from the response (e.g., color components, version numbers).
+     *
+     * @example
+     * ```typescript
+     * // Parse response data
+     * const match = data.match(feature.responseRegex);
+     * if (match) {
+     *   console.log("Feature detected, captured groups:", match.slice(1));
+     * }
+     * ```
+     */
+    responseRegex: RegExp;
+}
+/**
+ * Kitty Keyboard Protocol feature definition.
+ *
+ * The Kitty keyboard protocol provides enhanced keyboard input handling,
+ * including:
+ * - Distinguishing between key press and key release events
+ * - Reporting modifier keys as separate events
+ * - Providing Unicode code points for keys
+ *
+ * **Query sequence:** `ESC [ ? u`
+ *
+ * **Response format:** `ESC [ ? <flags> u`
+ * - `flags` is a decimal number indicating supported features
+ *
+ * @example Detecting Kitty protocol support
+ * ```typescript
+ * import { KittyFeature } from "tinky-termcap";
+ *
+ * // In a detection routine:
+ * stdout.write(KittyFeature.query);
+ *
+ * // When response arrives:
+ * const response = "\x1b[?1u";
+ * if (KittyFeature.responseRegex.test(response)) {
+ *   console.log("Kitty keyboard protocol is supported");
+ * }
+ * ```
+ *
+ * @see https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+ */
+export declare const KittyFeature: TermFeature;
+/**
+ * Background Color detection feature (OSC 11).
+ *
+ * Queries the terminal's current background color using Operating System
+ * Command (OSC) 11. This is useful for:
+ * - Adapting UI colors to light/dark themes
+ * - Ensuring sufficient contrast for text
+ * - Detecting the user's color scheme preference
+ *
+ * **Query sequence:** `ESC ] 11 ; ? ESC \`
+ *
+ * **Response format:** `ESC ] 11 ; rgb:<r>/<g>/<b> ST`
+ * - `r`, `g`, `b` are hex values (1-4 digits each)
+ * - `ST` (String Terminator) is either `ESC \` or `BEL` (0x07)
+ *
+ * @example Detecting background color
+ * ```typescript
+ * import { Osc11Feature } from "tinky-termcap";
+ *
+ * stdout.write(Osc11Feature.query);
+ *
+ * // Response might be: "\x1b]11;rgb:1a1a/1a1a/1a1a\x1b\\"
+ * const match = response.match(Osc11Feature.responseRegex);
+ * if (match) {
+ *   const [, r, g, b] = match;
+ *   console.log(`Background color: rgb(${r}, ${g}, ${b})`);
+ * }
+ * ```
+ *
+ * @see https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands
+ */
+export declare const Osc11Feature: TermFeature;
+/**
+ * Terminal Name detection feature (XTVERSION).
+ *
+ * Queries the terminal emulator's name and version using the XTVERSION
+ * control sequence. This information can be used for:
+ * - Enabling terminal-specific features
+ * - Logging and diagnostics
+ * - Adapting behavior for known terminal quirks
+ *
+ * **Query sequence:** `ESC [ > q`
+ *
+ * **Response format:** `DCS > | <name> ST`
+ * - `DCS` is Device Control String (`ESC P`)
+ * - `name` is the terminal name/version string
+ * - `ST` is String Terminator (`ESC \` or `BEL`)
+ *
+ * @example Detecting terminal name
+ * ```typescript
+ * import { TerminalNameFeature } from "tinky-termcap";
+ *
+ * stdout.write(TerminalNameFeature.query);
+ *
+ * // Response might be: "\x1bP>|xterm(388)\x1b\\"
+ * const match = response.match(TerminalNameFeature.responseRegex);
+ * if (match) {
+ *   console.log(`Terminal: ${match[1]}`); // "xterm(388)"
+ * }
+ * ```
+ *
+ * @see https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-PC-Style-Function-Keys
+ */
+export declare const TerminalNameFeature: TermFeature;
+/**
+ * Device Attributes detection feature (Primary DA).
+ *
+ * Queries the terminal's primary device attributes. This is commonly used
+ * as a "sentinel" query - terminals always respond to this, making it
+ * useful to determine when the terminal has finished responding to all
+ * capability queries.
+ *
+ * **Query sequence:** `ESC [ c`
+ *
+ * **Response format:** `ESC [ ? <params> c`
+ * - `params` is a semicolon-separated list of attribute codes
+ *
+ * @example Using as detection sentinel
+ * ```typescript
+ * import { DeviceAttributesFeature, KittyFeature, Osc11Feature } from "tinky-termcap";
+ *
+ * // Send multiple queries, with DA last as sentinel
+ * stdout.write(KittyFeature.query + Osc11Feature.query + DeviceAttributesFeature.query);
+ *
+ * // When DA response arrives, all other responses have been received
+ * if (DeviceAttributesFeature.responseRegex.test(buffer)) {
+ *   console.log("Detection complete");
+ * }
+ * ```
+ *
+ * @see https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Device-Status-Report
+ */
+export declare const DeviceAttributesFeature: TermFeature;
+/**
+ * Modify Other Keys feature detection.
+ *
+ * Queries the current modifyOtherKeys mode level. When enabled at level 2
+ * or higher, the terminal sends enhanced key sequences that distinguish
+ * between different key combinations (e.g., `Ctrl+I` vs `Tab`).
+ *
+ * **Query sequence:** `ESC [ > 4 ; ? m`
+ *
+ * **Response format:** `ESC [ > 4 ; <level> m`
+ * - `level` indicates the current modifyOtherKeys mode (0, 1, or 2)
+ *
+ * Level values:
+ * - `0`: Disabled
+ * - `1`: Basic mode (some enhanced sequences)
+ * - `2`: Full mode (all enhanced sequences)
+ *
+ * @example Detecting modifyOtherKeys support
+ * ```typescript
+ * import { ModifyOtherKeysFeature } from "tinky-termcap";
+ *
+ * stdout.write(ModifyOtherKeysFeature.query);
+ *
+ * // Response might be: "\x1b[>4;2m"
+ * const match = response.match(ModifyOtherKeysFeature.responseRegex);
+ * if (match) {
+ *   const level = parseInt(match[1], 10);
+ *   console.log(`modifyOtherKeys level: ${level}`);
+ *   if (level >= 2) {
+ *     console.log("Full keyboard disambiguation available");
+ *   }
+ * }
+ * ```
+ *
+ * @see https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Functions-using-CSI-_-Desktop-Notification
+ */
+export declare const ModifyOtherKeysFeature: TermFeature;

package/lib/utils/term-features.js

@@ -0,0 +1,208 @@
+"use strict";
+/**
+ * @fileoverview Terminal feature query definitions for capability detection.
+ *
+ * This module defines the query sequences and response patterns for detecting
+ * various terminal capabilities. Each feature is represented as a `TermFeature`
+ * object containing the ANSI escape sequence to query the feature and a regex
+ * pattern to match the terminal's response.
+ *
+ * @example
+ * ```typescript
+ * import { KittyFeature, Osc11Feature } from "tinky-termcap/utils/term-features";
+ *
+ * // Send query to terminal
+ * process.stdout.write(KittyFeature.query);
+ *
+ * // Parse response
+ * const response = "\\x1b[?1u";
+ * if (KittyFeature.responseRegex.test(response)) {
+ *   console.log("Kitty keyboard protocol is supported!");
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModifyOtherKeysFeature = exports.DeviceAttributesFeature = exports.TerminalNameFeature = exports.Osc11Feature = exports.KittyFeature = void 0;
+/**
+ * Escape character constant used in ANSI escape sequences.
+ * @internal
+ */
+var ESC = "\x1b";
+/**
+ * Kitty Keyboard Protocol feature definition.
+ *
+ * The Kitty keyboard protocol provides enhanced keyboard input handling,
+ * including:
+ * - Distinguishing between key press and key release events
+ * - Reporting modifier keys as separate events
+ * - Providing Unicode code points for keys
+ *
+ * **Query sequence:** `ESC [ ? u`
+ *
+ * **Response format:** `ESC [ ? <flags> u`
+ * - `flags` is a decimal number indicating supported features
+ *
+ * @example Detecting Kitty protocol support
+ * ```typescript
+ * import { KittyFeature } from "tinky-termcap";
+ *
+ * // In a detection routine:
+ * stdout.write(KittyFeature.query);
+ *
+ * // When response arrives:
+ * const response = "\x1b[?1u";
+ * if (KittyFeature.responseRegex.test(response)) {
+ *   console.log("Kitty keyboard protocol is supported");
+ * }
+ * ```
+ *
+ * @see https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+ */
+exports.KittyFeature = {
+    query: "".concat(ESC, "[?u"),
+    responseRegex: new RegExp("".concat(ESC, "\\[\\?(\\d+)u")),
+};
+/**
+ * Background Color detection feature (OSC 11).
+ *
+ * Queries the terminal's current background color using Operating System
+ * Command (OSC) 11. This is useful for:
+ * - Adapting UI colors to light/dark themes
+ * - Ensuring sufficient contrast for text
+ * - Detecting the user's color scheme preference
+ *
+ * **Query sequence:** `ESC ] 11 ; ? ESC \`
+ *
+ * **Response format:** `ESC ] 11 ; rgb:<r>/<g>/<b> ST`
+ * - `r`, `g`, `b` are hex values (1-4 digits each)
+ * - `ST` (String Terminator) is either `ESC \` or `BEL` (0x07)
+ *
+ * @example Detecting background color
+ * ```typescript
+ * import { Osc11Feature } from "tinky-termcap";
+ *
+ * stdout.write(Osc11Feature.query);
+ *
+ * // Response might be: "\x1b]11;rgb:1a1a/1a1a/1a1a\x1b\\"
+ * const match = response.match(Osc11Feature.responseRegex);
+ * if (match) {
+ *   const [, r, g, b] = match;
+ *   console.log(`Background color: rgb(${r}, ${g}, ${b})`);
+ * }
+ * ```
+ *
+ * @see https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands
+ */
+exports.Osc11Feature = {
+    query: "".concat(ESC, "]11;?").concat(ESC, "\\"),
+    responseRegex: new RegExp("".concat(ESC, "\\]11;rgb:([0-9a-fA-F]{1,4})\\/([0-9a-fA-F]{1,4})\\/([0-9a-fA-F]{1,4})(").concat(ESC, "\\\\|\\x07)?")),
+};
+/**
+ * Terminal Name detection feature (XTVERSION).
+ *
+ * Queries the terminal emulator's name and version using the XTVERSION
+ * control sequence. This information can be used for:
+ * - Enabling terminal-specific features
+ * - Logging and diagnostics
+ * - Adapting behavior for known terminal quirks
+ *
+ * **Query sequence:** `ESC [ > q`
+ *
+ * **Response format:** `DCS > | <name> ST`
+ * - `DCS` is Device Control String (`ESC P`)
+ * - `name` is the terminal name/version string
+ * - `ST` is String Terminator (`ESC \` or `BEL`)
+ *
+ * @example Detecting terminal name
+ * ```typescript
+ * import { TerminalNameFeature } from "tinky-termcap";
+ *
+ * stdout.write(TerminalNameFeature.query);
+ *
+ * // Response might be: "\x1bP>|xterm(388)\x1b\\"
+ * const match = response.match(TerminalNameFeature.responseRegex);
+ * if (match) {
+ *   console.log(`Terminal: ${match[1]}`); // "xterm(388)"
+ * }
+ * ```
+ *
+ * @see https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-PC-Style-Function-Keys
+ */
+exports.TerminalNameFeature = {
+    query: "".concat(ESC, "[>q"),
+    responseRegex: new RegExp("".concat(ESC, "P>\\|(.+?)(").concat(ESC, "\\\\|\\x07)")),
+};
+/**
+ * Device Attributes detection feature (Primary DA).
+ *
+ * Queries the terminal's primary device attributes. This is commonly used
+ * as a "sentinel" query - terminals always respond to this, making it
+ * useful to determine when the terminal has finished responding to all
+ * capability queries.
+ *
+ * **Query sequence:** `ESC [ c`
+ *
+ * **Response format:** `ESC [ ? <params> c`
+ * - `params` is a semicolon-separated list of attribute codes
+ *
+ * @example Using as detection sentinel
+ * ```typescript
+ * import { DeviceAttributesFeature, KittyFeature, Osc11Feature } from "tinky-termcap";
+ *
+ * // Send multiple queries, with DA last as sentinel
+ * stdout.write(KittyFeature.query + Osc11Feature.query + DeviceAttributesFeature.query);
+ *
+ * // When DA response arrives, all other responses have been received
+ * if (DeviceAttributesFeature.responseRegex.test(buffer)) {
+ *   console.log("Detection complete");
+ * }
+ * ```
+ *
+ * @see https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Device-Status-Report
+ */
+exports.DeviceAttributesFeature = {
+    query: "".concat(ESC, "[c"),
+    responseRegex: new RegExp("".concat(ESC, "\\[\\?(\\d+)(;\\d+)*c")),
+};
+/**
+ * Modify Other Keys feature detection.
+ *
+ * Queries the current modifyOtherKeys mode level. When enabled at level 2
+ * or higher, the terminal sends enhanced key sequences that distinguish
+ * between different key combinations (e.g., `Ctrl+I` vs `Tab`).
+ *
+ * **Query sequence:** `ESC [ > 4 ; ? m`
+ *
+ * **Response format:** `ESC [ > 4 ; <level> m`
+ * - `level` indicates the current modifyOtherKeys mode (0, 1, or 2)
+ *
+ * Level values:
+ * - `0`: Disabled
+ * - `1`: Basic mode (some enhanced sequences)
+ * - `2`: Full mode (all enhanced sequences)
+ *
+ * @example Detecting modifyOtherKeys support
+ * ```typescript
+ * import { ModifyOtherKeysFeature } from "tinky-termcap";
+ *
+ * stdout.write(ModifyOtherKeysFeature.query);
+ *
+ * // Response might be: "\x1b[>4;2m"
+ * const match = response.match(ModifyOtherKeysFeature.responseRegex);
+ * if (match) {
+ *   const level = parseInt(match[1], 10);
+ *   console.log(`modifyOtherKeys level: ${level}`);
+ *   if (level >= 2) {
+ *     console.log("Full keyboard disambiguation available");
+ *   }
+ * }
+ * ```
+ *
+ * @see https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Functions-using-CSI-_-Desktop-Notification
+ */
+exports.ModifyOtherKeysFeature = {
+    query: "".concat(ESC, "[>4;?m"),
+    responseRegex: new RegExp("".concat(ESC, "\\[>4;(\\d+)m")),
+};

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "tinky-termcap",
+  "version": "0.1.0",
+  "description": "Terminal capability detection for Tinky - React hooks for Kitty protocol, background color, terminal name detection",
+  "keywords": [
+    "terminal",
+    "capability",
+    "kitty",
+    "xterm",
+    "tinky",
+    "react",
+    "hooks"
+  ],
+  "homepage": "https://github.com/ByteLandTechnology/tinky-termcap#readme",
+  "bugs": {
+    "url": "https://github.com/ByteLandTechnology/tinky-termcap/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ByteLandTechnology/tinky-termcap.git"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "ByteLand Technology Limited"
+  },
+  "type": "module",
+  "main": "./lib/index.js",
+  "typings": "./lib/index.d.ts",
+  "files": [
+    "./lib/*"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "build": "tsc && npm run docs",
+    "lint": "eslint src tests",
+    "prepublish": "npm run build",
+    "prepare": "husky",
+    "docs": "typedoc --plugin typedoc-plugin-markdown --disableSources --out docs/api && prettier --write docs/api"
+  },
+  "peerDependencies": {
+    "tinky": "^1.1.2"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.3.0",
+    "@commitlint/config-conventional": "^20.3.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.0",
+    "@semantic-release/npm": "^13.1.3",
+    "@types/bun": "^1.3.6",
+    "@types/react": "^19.2.8",
+    "@types/react-dom": "^19.2.3",
+    "eslint": "^9.39.2",
+    "eslint-plugin-react": "^7.37.5",
+    "husky": "^9.1.7",
+    "jiti": "^2.6.1",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.7.4",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "typedoc": "^0.28.16",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "typescript-eslint": "^8.53.0"
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "lint-staged": {
+    "*.{js,ts,jsx,tsx,json,md,yaml,yml}": "prettier --write"
+  }
+}