added docs to describe the improvement for device and terminal detection

Author: stalep

content/docs/readline/_index.md

@@ -42,6 +42,7 @@ Think of it this way: Æsh is built **on top of** Æsh Readline. Æsh provides t
 - **Stream Support** - Standard out and standard error handling
 - **Shell Features** - Redirect, alias, and pipeline support
 - **Remote Connectivity** - SSH, Telnet, and WebSocket terminal servers
+- **[Terminal Environment](terminal-environment)** - Centralized terminal detection (type, color depth, multiplexers)
 - **[Color Detection](color-detection)** - Automatic terminal theme and color depth detection
 - **[Terminal Colors](terminal-colors)** - RGB colors, theme-aware styling, and color depth adaptation
 - **[Device Attributes](device-attributes)** - DA1/DA2 terminal capability queries

content/docs/readline/color-detection.md

@@ -305,13 +305,20 @@ See [Terminal Colors](terminal-colors#ansi-color-utilities) for complete documen
 
 ### 2. Environment Variables
 
-Checks standard environment variables:
+Checks standard environment variables via [`TerminalEnvironment`](terminal-environment):
 
 | Variable | Example | Meaning |
 |----------|---------|---------|
 | `COLORFGBG` | `15;0` | Foreground;Background color indices |
 | `COLORTERM` | `truecolor` | Color depth hint |
 | `APPLE_INTERFACE_STYLE` | `Dark` | macOS dark mode |
+| `TERM_PROGRAM` | `iTerm.app` | Terminal program identifier |
+| `KITTY_WINDOW_ID` | `1` | Kitty terminal indicator |
+| `ITERM_SESSION_ID` | `w0t0p0` | iTerm2 session indicator |
+| `WEZTERM_PANE` | `0` | WezTerm terminal indicator |
+| `GHOSTTY_RESOURCES_DIR` | `/path` | Ghostty terminal indicator |
+
+The `TerminalEnvironment` class parses these once and caches the results. See [Terminal Environment](terminal-environment) for details on all supported environment variables and terminal types.
 
 ### 3. Terminal-Specific Detection
 
@@ -346,17 +353,31 @@ Queries the Windows registry for `AppsUseLightTheme`.
 
 ## Multiplexer Support (tmux/screen)
 
-When running inside tmux or GNU Screen, color detection requires special handling:
+When running inside tmux or GNU Screen, color detection requires special handling. The [`TerminalEnvironment`](terminal-environment) class provides centralized multiplexer detection:
 
 ```java
+import org.aesh.terminal.utils.TerminalEnvironment;
+
+TerminalEnvironment env = TerminalEnvironment.getInstance();
+
 // Check if running in a multiplexer
-if (TerminalColorDetector.isRunningInTmux()) {
+if (env.isInTmux()) {
     System.out.println("Running inside tmux");
 }
 
-if (TerminalColorDetector.isRunningInMultiplexer()) {
+if (env.isInMultiplexer()) {
     System.out.println("Running inside tmux or screen");
 }
+
+// Check if passthrough is enabled
+if (env.isTmuxPassthroughEnabled()) {
+    System.out.println("OSC passthrough is enabled");
+}
+
+// Legacy static methods still work
+if (TerminalColorDetector.isRunningInTmux()) {
+    System.out.println("Running inside tmux");
+}
 ```
 
 ### tmux Passthrough

content/docs/readline/connection.md

@@ -235,20 +235,53 @@ int[] rgb = connection.queryOsc(4, 1, "?", 500,
 
 ### OSC Support Detection
 
-Check if the terminal supports OSC queries:
+Not all terminals support all OSC queries. For example, JetBrains IDE terminals
+don't support OSC 4 (palette queries). Use the `Device` enums to check
+terminal capabilities before querying:
 
 ```java
-// Basic heuristic check
-boolean supportsOsc = connection.supportsOscQueries();
+import org.aesh.terminal.Device.TerminalType;
+import org.aesh.terminal.Device.OscCode;
 
-// More accurate check using Device Attributes
-DeviceAttributes attrs = connection.queryPrimaryDeviceAttributes(500);
-boolean supportsOsc = connection.supportsOscQueries(attrs);
+// Detect terminal type from environment
+TerminalType termType = connection.getTerminalType();
+System.out.println("Terminal: " + termType.getIdentifier());
 
-// Query-based check (sends DA1 query)
-boolean supportsOsc = connection.querySupportsOscQueries(500);
+// Check specific OSC support
+if (connection.supportsPaletteQuery()) {
+    int[] color = connection.queryPaletteColor(1, 500);
+    // Use color...
+}
+
+// Or use the convenience method that checks support first
+int[] color = connection.queryPaletteColorIfSupported(1, 500);
+if (color != null) {
+    // Terminal supports OSC 4 and returned a color
+}
+
+// Check for OSC 10/11 support
+if (connection.supportsColorQuery()) {
+    int[] fg = connection.queryForegroundColor(500);
+    int[] bg = connection.queryBackgroundColor(500);
+}
+
+// Check if running in JetBrains IDE
+Device device = connection.device();
+if (device != null && device.isJetBrainsTerminal()) {
+    // Use fallback approach for palette colors
+}
+
+// Check for any OSC code support
+if (connection.supportsOscCode(OscCode.CLIPBOARD)) {
+    // Terminal supports clipboard access via OSC 52
+}
 ```
 
+Known terminal limitations:
+- **JetBrains IDEs**: No OSC 4 (palette) support
+- **Linux console**: No OSC query support
+- **Alacritty**: No OSC 52 (clipboard) support
+
 ## Device Attributes (DA1/DA2)
 
 Device Attributes queries allow you to detect terminal capabilities that cannot be determined from terminfo alone.

content/docs/readline/device-attributes.md

@@ -282,6 +282,95 @@ if (da != null) {
 }
 ```
 
+## Synergy with Terminal Environment
+
+The `DeviceAttributes` class provides synergy methods that work with [`TerminalEnvironment`](terminal-environment) and `Device.TerminalType` for comprehensive terminal detection:
+
+### Inferring Terminal Type from DA
+
+```java
+import org.aesh.terminal.Device;
+import org.aesh.terminal.utils.TerminalEnvironment;
+
+// Heuristic detection (fast, always available)
+Device.TerminalType heuristicType = TerminalEnvironment.detectTerminalType();
+
+// Authoritative detection from DA1/DA2
+DeviceAttributes da = connection.queryDeviceAttributes(500);
+if (da != null) {
+    Device.TerminalType authType = da.inferTerminalType();
+    System.out.println("Inferred type: " + authType.getIdentifier());
+}
+```
+
+### Validating Terminal Type
+
+Verify that heuristic detection matches actual capabilities:
+
+```java
+Device.TerminalType envType = TerminalEnvironment.detectTerminalType();
+DeviceAttributes da = connection.queryDeviceAttributes(500);
+
+if (da != null && !da.matchesTerminalType(envType)) {
+    System.out.println("Warning: Terminal capabilities differ from expected for " +
+                       envType.getIdentifier());
+}
+```
+
+### Inferring Color Depth
+
+Get authoritative color depth from DA1:
+
+```java
+DeviceAttributes da = connection.queryDeviceAttributes(500);
+if (da != null) {
+    ColorDepth depth = da.inferColorDepth();
+    System.out.println("Color depth: " + depth);
+}
+```
+
+### Capability Summary
+
+Generate a comprehensive capabilities report:
+
+```java
+Device.TerminalType envType = TerminalEnvironment.detectTerminalType();
+DeviceAttributes da = connection.queryDeviceAttributes(500);
+
+if (da != null) {
+    String summary = da.getCapabilitySummary(envType);
+    System.out.println(summary);
+}
+```
+
+Output example:
+```
+Terminal: kitty
+DA1 Class: 64
+DA2 Type: VT420
+
+Capabilities:
+  Color Depth: COLORS_256
+  Sixel Graphics: Yes
+  ANSI Color: Yes
+  Mouse Support: Yes
+  OSC Queries: Likely
+```
+
+### Expected Features by Terminal Type
+
+Each `Device.TerminalType` knows its expected DA1 features:
+
+```java
+// Get expected features for a terminal type
+Set<DeviceAttributes.Feature> expected = Device.TerminalType.KITTY.getExpectedFeatures();
+// Contains: SIXEL, ANSI_COLOR, ANSI_TEXT_LOCATOR
+
+// Convenience methods
+boolean expectsSixel = Device.TerminalType.KITTY.expectsSixel();  // true
+boolean expectsMouse = Device.TerminalType.XTERM.expectsMouse();  // true
+```
+
 ## Common DA1 Response Patterns
 
 Different terminals return different DA1 responses: