Core: introduce VTCapabilities

Introduce the infrastructure to query the terminal what it actually
supports. This allows the safe use of advanced features and will allow
defaulting to 8-bit encoding if the terminal supports 8-bit encoding
rather than the 7-bit encoding.

Author: compnerd

Sources/VirtualTerminal/Input/VTEvent.swift

@@ -80,6 +80,7 @@ extension KeyModifiers {
 public enum KeyEventType: Equatable, Sendable {
   case press
   case release
+  case response(VTDeviceAttributesResponse)
 }
 
 /// A keyboard input event with character and modifier information.

Sources/VirtualTerminal/Input/VTInputParser.swift

@@ -72,6 +72,22 @@ internal enum ParseResult<Output> {
   case indeterminate
 }
 
+/// Device attribute response types based on intermediate characters.
+///
+/// Different device attribute queries return different types of information.
+/// The intermediate character in the CSI sequence indicates which type of
+/// response is being provided.
+public enum VTDeviceAttributesResponse: Equatable, Sendable {
+  /// Primary device attributes (DA1) - basic terminal identification
+  case primary([Int])
+
+  /// Secondary device attributes (DA2) - version and capability info
+  case secondary([Int])
+
+  /// Tertiary device attributes (DA3) - unit identification
+  case tertiary([Int])
+}
+
 /// Represents different types of parsed terminal input sequences.
 ///
 /// Terminal input consists of various sequence types, from simple characters
@@ -86,6 +102,7 @@ internal enum ParseResult<Output> {
 internal enum ParsedSequence {
   case character(Character)
   case cursor(direction: Direction, count: Int)
+  case DeviceAttributes(VTDeviceAttributesResponse)
   case function(number: Int, modifiers: KeyModifiers)
   case unknown(sequence: [UInt8])
 }
@@ -307,6 +324,21 @@ extension VTInputParser {
       input = input.dropFirst()
       return parse(next: &input)
 
+    case 0x3d: // '=' (DEC Private Mode)
+      state = .CSI(parameters: parameters, intermediate: intermediate + [byte])
+      input = input.dropFirst()
+      return parse(next: &input)
+
+    case 0x3e: // '>' (DEC Private Mode)
+      state = .CSI(parameters: parameters, intermediate: intermediate + [byte])
+      input = input.dropFirst()
+      return parse(next: &input)
+
+    case 0x3f: // '?' (DEC Private Mode)
+      state = .CSI(parameters: parameters, intermediate: intermediate + [byte])
+      input = input.dropFirst()
+      return parse(next: &input)
+
     case 0x40 ... 0x7e: // command
       state = .normal
       input = input.dropFirst()
@@ -376,7 +408,8 @@ extension VTInputParser {
       }
       input = input.dropFirst(2)
       state = .normal
-      return .success(.unknown(sequence: [0x1b, 0x50] + data), buffer: input)
+      return .success(.unknown(sequence: [0x1b, 0x50] + data + [0x1b, byte]),
+                      buffer: input)
     }
 
     input = input.dropFirst()
@@ -416,6 +449,12 @@ extension VTInputParser {
       return .cursor(direction: .right, count: count)
     case 0x44:  // 'D' (CUB)
       return .cursor(direction: .left, count: count)
+    case 0x63 where intermediate == [0x3f]:  // '\033[?...c' (DA1)
+      return .DeviceAttributes(.primary(parameters))
+    case 0x63 where intermediate == [0x3e]:  // '\033[>...c' (DA2)
+      return .DeviceAttributes(.secondary(parameters))
+    case 0x63 where intermediate == [0x3d]:  // '\033[=...c' (DA3)
+      return .DeviceAttributes(.tertiary(parameters))
     default:
       let sequence: [UInt8] = [UInt8(0x1b), UInt8(0x5b)] + parameters.flatMap { String($0).utf8 } + [UInt8(0x3b)] + intermediate + [command]
       return .unknown(sequence: sequence)
@@ -476,6 +515,10 @@ extension ParsedSequence {
                  type: .press)
       }
 
+    case let .DeviceAttributes(attributes):
+      KeyEvent(character: nil, keycode: 0, modifiers: [],
+               type: .response(attributes))
+
     case let .function(number, modifiers):
       KeyEvent(character: nil,
                keycode: UInt16(Int(VTKeyCode.F1) + number - 1),

Sources/VirtualTerminal/Rendering/VTRenderer.swift

@@ -133,6 +133,8 @@ extension VTBuffer {
 public final class VTRenderer: Sendable {
   /// The underlying platform-specific terminal implementation.
   private let _terminal: PlatformTerminal
+  /// The terminal capabilities.
+  private let capabilities: VTCapabilities
   /// The currently displayed buffer state (visible to the user).
   package nonisolated(unsafe) var front: VTBuffer
   /// The buffer where new content is drawn (back buffer for double buffering).
@@ -157,6 +159,7 @@ public final class VTRenderer: Sendable {
   /// - Throws: Terminal initialization errors
   public init(mode: VTMode) async throws {
     self._terminal = try await PlatformTerminal(mode: mode)
+    self.capabilities = await VTCapabilities.query(self._terminal) ?? .unknown
     self.front = VTBuffer(size: _terminal.size)
     self.back = VTBuffer(size: _terminal.size)
   }

Sources/VirtualTerminal/Terminal/VTCapabilities.swift

@@ -0,0 +1,149 @@
+// Copyright © 2025 Saleem Abdulrasool <compnerd@compnerd.org>
+// SPDX-License-Identifier: BSD-3-Clause
+
+public enum DECTerminalType: UInt8 {
+  // VT100 Series
+
+  // VT125 Series (Graphics)
+  case VT125 = 12           // VT125 with ReGIS graphics
+
+  // VT200 Series
+  case VT220 = 62           // VT220
+
+  // VT300 Series
+  case VT320 = 63           // VT320
+
+  // VT400 Series
+  case VT420 = 64           // VT420
+}
+
+extension DECTerminalType: Sendable { }
+extension DECTerminalType: CaseIterable { }
+
+public enum VTDAFeature: UInt8 {
+  case ExtendedColumns = 1  // 132 columns
+  case PrinterPort = 2
+  case ReGISGraphics = 3
+  case SixelGraphics = 4
+  case SelectiveErase = 6
+  case SoftCharacterSet = 7
+  case UserDefinedKeys = 8
+  case NationalReplacementCharacterSet = 9
+  case SerboCroatianCharacterSet = 12
+  case EightBitInterfaceArchitecture = 14
+  case TechnicalCharacterSet = 15
+  case LocatorPort = 16
+  case TerminalStateInterrogation = 17
+  case WindowingCapability = 18
+  case Sessions = 19
+  case HorizontalScrolling = 21
+  case ANSIColor = 22
+  case GreekCharacterSet = 23
+  case TurkishCharacterSet = 24
+  case RectangularAreaOperations = 28
+  case ANSITextLocator = 29
+  case TextMacros = 32
+  case ISOLatin2CharacterSet = 42
+  case PCTerm = 44
+  case SoftKeyMapping = 45
+  case ASCIIEmulation = 46
+  case ClipboardAccess = 52
+}
+
+public struct VTExtensions: Sendable, OptionSet {
+  public typealias RawValue = VTDAFeature.RawValue
+
+  public let rawValue: RawValue
+
+  public init(rawValue: RawValue) {
+    self.rawValue = rawValue
+  }
+
+  internal init(_ parameter: VTDAFeature) {
+    self.init(rawValue: 1 << parameter.rawValue)
+  }
+}
+
+extension VTExtensions {
+  public static var none: VTExtensions {
+    VTExtensions(rawValue: 0)
+  }
+}
+
+public struct VTCapabilities: Sendable {
+  public let standard: DECTerminalType?
+  public let features: VTExtensions
+
+}
+
+extension VTCapabilities {
+  /// Queries the terminal to determine its capabilities and supported features.
+  ///
+  /// Use this method to detect what your terminal supports instead of making assumptions
+  /// or relying on environment variables. This allows your application to gracefully
+  /// adapt its behavior based on actual terminal capabilities.
+  ///
+  /// ```swift
+  /// if let capabilities = await VTCapabilities.query(terminal) {
+  ///     if capabilities.features.contains(.ANSIColor) {
+  ///         // Safe to use colors
+  ///         await terminal <<< .SelectGraphicRendition([.foreground(.red)])
+  ///     }
+  /// } else {
+  ///     // Use basic functionality only
+  /// }
+  /// ```
+  ///
+  /// - Parameters:
+  ///   - terminal: The terminal to query
+  ///   - timeout: How long to wait for a response (default: 250ms)
+  /// - Returns: Terminal capabilities, or `nil` if detection failed
+  public static func query(_ terminal: some VTTerminal,
+                           timeout: Duration = .milliseconds(250)) async
+      -> VTCapabilities? {
+    return await withTaskGroup(of: Void.self) { group in
+      defer { group.cancelAll() }
+
+      var capabilities: VTCapabilities?
+
+      group.addTask {
+        capabilities = try? await Task<VTCapabilities, Error>.withTimeout(timeout: timeout) {
+          for try await event in terminal.input {
+            if case let .key(event) = event, case let .response(attributes) = event.type {
+              let standard: DECTerminalType? =
+                  if case let .some(value) = attributes.first,
+                      let id = UInt8(exactly: value) {
+                    DECTerminalType(rawValue: id)
+                  } else {
+                    nil
+                  }
+
+              let features = attributes.dropFirst()
+                                .compactMap(UInt8.init(exactly:))
+                                .compactMap(VTDAFeature.init(rawValue:))
+                                .compactMap(VTExtensions.init)
+                                .reduce(into: VTExtensions()) { $0.formUnion($1) }
+
+              return VTCapabilities(standard: standard, features: features)
+            }
+          }
+          return .unknown
+        }
+      }
+
+      group.addTask {
+        await terminal <<< .DeviceAttributes(.Request)
+      }
+
+      await group.waitForAll()
+
+      return capabilities
+    }
+  }
+}
+
+extension VTCapabilities {
+  public static var unknown: VTCapabilities {
+    VTCapabilities(standard: nil, features: [])
+  }
+}