updated the latest api changes to connection and color detection

Author: stalep

content/docs/readline/_index.md

@@ -43,7 +43,7 @@ Think of it this way: Æsh is built **on top of** Æsh Readline. Æsh provides t
 - **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
+- **[Color Detection](color-detection)** - Automatic terminal theme detection with batch queries and fallbacks
 - **[Terminal Colors](terminal-colors)** - RGB/HSL colors, theme-aware styling, and color depth adaptation
 - **[Device Attributes](device-attributes)** - DA1/DA2 terminal capability queries
 - **[Terminal Images](terminal-images)** - Sixel, Kitty, and iTerm2 inline image support

content/docs/readline/color-detection.md

@@ -76,10 +76,24 @@ boolean has256 = depth.supports256Colors();
 boolean hasTrueColor = depth.supportsTrueColor();
 
 // Actual RGB colors (may be null if not detectable)
-int[] bgRGB = cap.getBackgroundRGB();  // [r, g, b] or null
-int[] fgRGB = cap.getForegroundRGB();  // [r, g, b] or null
+int[] fgRGB = cap.getForegroundRGB();     // [r, g, b] or null
+int[] bgRGB = cap.getBackgroundRGB();     // [r, g, b] or null
+int[] cursorRGB = cap.getCursorRGB();     // [r, g, b] or null
+
+// Palette colors (ANSI 16 colors, indices 0-15)
+if (cap.hasPaletteColors()) {
+    Map<Integer, int[]> palette = cap.getPaletteColors();
+    int[] red = cap.getPaletteColor(1);   // Standard red
+    int[] brightRed = cap.getPaletteColor(9);  // Bright red
+}
 ```
 
+The `detect()` method queries:
+- Foreground color (OSC 10)
+- Background color (OSC 11)
+- Cursor color (OSC 12) - if supported
+- ANSI 16 palette colors (OSC 4, indices 0-15) - if supported
+
 ### Suggested Color Codes
 
 Get ANSI color codes that work well with the detected theme:
@@ -257,6 +271,62 @@ int[] cursor = connection.queryCursorColor(500);
 String result = connection.queryOsc(oscCode, "?", 500, responseParser);
 ```
 
+#### Batch Color Queries
+
+For better performance when querying multiple colors, use batch queries. This reduces latency from O(n × timeout) to O(timeout) by sending all queries at once:
+
+```java
+import org.aesh.terminal.tty.TerminalColorDetector;
+import org.aesh.terminal.utils.ANSI;
+
+// Query foreground, background, and cursor in one operation (~50-100ms vs ~600ms)
+Map<Integer, int[]> colors = TerminalColorDetector.queryColors(connection, 500);
+
+int[] fg = colors.get(ANSI.OSC_FOREGROUND);   // OSC 10
+int[] bg = colors.get(ANSI.OSC_BACKGROUND);   // OSC 11
+int[] cursor = colors.get(ANSI.OSC_CURSOR_COLOR);  // OSC 12
+
+// Query multiple palette colors at once
+Map<Integer, int[]> palette = TerminalColorDetector.queryPaletteColors(
+    connection, 500, 0, 1, 2, 3, 4, 5, 6, 7);
+
+// Query all 16 ANSI colors
+Map<Integer, int[]> ansi16 = TerminalColorDetector.queryAnsi16Colors(connection, 500);
+```
+
+#### Fallback When OSC Not Supported
+
+Not all terminals support OSC queries. Use `queryColorsWithFallback()` for graceful degradation:
+
+```java
+// Always returns colors - actual or estimated based on environment
+Map<Integer, int[]> colors = TerminalColorDetector.queryColorsWithFallback(connection, 500);
+
+int[] bg = colors.get(ANSI.OSC_BACKGROUND);
+// bg is never null - will be estimated if OSC queries failed
+
+// Check if it's a dark theme
+boolean isDark = TerminalColorDetector.isDarkColor(bg);
+```
+
+You can also check support before querying:
+
+```java
+// Check if OSC queries are supported
+if (TerminalColorDetector.isOscColorQuerySupported(connection)) {
+    // OSC queries will work
+    Map<Integer, int[]> colors = TerminalColorDetector.queryColors(connection, 500);
+} else {
+    // Use environment-based detection
+    TerminalTheme theme = TerminalColorDetector.detectThemeFromEnvironment();
+}
+
+// Check palette query support specifically
+if (connection.supportsPaletteQuery()) {
+    Map<Integer, int[]> palette = TerminalColorDetector.queryAnsi16Colors(connection, 500);
+}
+```
+
 #### OSC Support Detection with Device Attributes
 
 Use DA1 device attributes to determine if OSC queries are likely to work:

content/docs/readline/connection.md

@@ -35,6 +35,22 @@ connection.openNonBlocking();
 
 Reads input in a separate thread, allowing the current thread to continue.
 
+#### Checking Reading State
+
+```java
+// Check if connection is actively reading
+if (connection.reading()) {
+    // Handler-based queries work (setStdinHandler)
+} else {
+    // Use synchronous methods like queryColorCapability()
+}
+```
+
+The `reading()` method returns `true` after `openBlocking()` or `openNonBlocking()` is called
+and before `close()` is called. This is useful for determining which query methods to use:
+- When `reading()` is true: Handler-based methods like `queryTerminal()` work
+- When `reading()` is false: Use synchronous methods like `queryColorCapability()`
+
 ## Handlers
 
 ### Standard Input Handler
@@ -282,6 +298,39 @@ Known terminal limitations:
 - **Linux console**: No OSC query support
 - **Alacritty**: No OSC 52 (clipboard) support
 
+### Batch OSC Queries
+
+For better performance when querying multiple colors, use batch queries. This sends all queries at once and collects responses together, reducing latency from O(n × timeout) to O(timeout):
+
+```java
+// Query foreground, background, and cursor colors in one operation
+// Takes ~50-100ms instead of ~300-400ms for individual queries
+Map<Integer, int[]> colors = connection.queryColors(500);
+
+int[] fg = colors.get(ANSI.OSC_FOREGROUND);   // OSC 10
+int[] bg = colors.get(ANSI.OSC_BACKGROUND);   // OSC 11
+int[] cursor = colors.get(ANSI.OSC_CURSOR_COLOR);  // OSC 12
+
+// Query multiple palette colors at once
+Map<Integer, int[]> palette = connection.queryPaletteColors(500, 0, 1, 2, 3, 4, 5, 6, 7);
+
+// Query all 16 ANSI colors
+Map<Integer, int[]> ansi16 = connection.queryAnsi16Colors(500);
+
+// Generic batch query for any OSC codes
+Map<Integer, int[]> results = connection.queryBatchOsc(500, 10, 11, 12);
+```
+
+For higher-level access with automatic fallbacks, use `TerminalColorDetector`:
+
+```java
+import org.aesh.terminal.tty.TerminalColorDetector;
+
+// Query with automatic fallback to environment-based detection
+Map<Integer, int[]> colors = TerminalColorDetector.queryColorsWithFallback(connection, 500);
+// Always returns colors - actual if OSC works, estimated if not
+```
+
 ## Device Attributes (DA1/DA2)
 
 Device Attributes queries allow you to detect terminal capabilities that cannot be determined from terminfo alone.
@@ -407,7 +456,17 @@ if (depth.supportsTrueColor()) {
     // Use 256-color palette
 }
 
-// Get full color capability info
-TerminalColorCapability cap = connection.getColorCapability();
-TerminalTheme theme = cap.getTheme();
+// Query terminal for full color capability (uses synchronous I/O)
+// This can be called BEFORE openBlocking/openNonBlocking
+TerminalColorCapability cap = connection.queryColorCapability(500);
+if (cap != null) {
+    TerminalTheme theme = cap.getTheme();
+    int[] fg = cap.getForegroundRGB();
+    int[] bg = cap.getBackgroundRGB();
+    int[] cursor = cap.getCursorRGB();
+    Map<Integer, int[]> palette = cap.getPaletteColors();
+}
+
+// Or use TerminalColorDetector for comprehensive detection with fallbacks
+TerminalColorCapability cap = TerminalColorDetector.detect(connection);
 ```

content/docs/readline/connectivity.md

@@ -55,14 +55,14 @@ SSH (Secure Shell) provides encrypted, authenticated terminal access. This is th
 <dependency>
     <groupId>org.aesh</groupId>
     <artifactId>aesh-terminal-ssh</artifactId>
-    <version>2.6</version>
+    <version>3.1</version>
 </dependency>
 ```
 
 ### Gradle Dependency
 
 ```groovy
-implementation 'org.aesh:aesh-terminal-ssh:2.6'
+implementation 'org.aesh:aesh-terminal-ssh:3.1'
 ```
 
 ### Basic SSH Server
@@ -318,7 +318,7 @@ Telnet provides simple, unencrypted terminal access. **Use only for development
 <dependency>
     <groupId>org.aesh</groupId>
     <artifactId>aesh-terminal-telnet</artifactId>
-    <version>2.6</version>
+    <version>3.1</version>
 </dependency>
 ```
 
@@ -398,7 +398,7 @@ The terminal-http module provides:
 <dependency>
     <groupId>org.aesh</groupId>
     <artifactId>terminal-http</artifactId>
-    <version>3.0</version>
+    <version>3.1</version>
 </dependency>
 ```
 
@@ -751,33 +751,59 @@ All remote terminals provide a `Connection` object with the same interface:
 
 ```java
 public interface Connection {
-    
+
     // Write to terminal
     void write(String text);
     void write(byte[] bytes);
     void write(int[] codepoints);
-    
+
     // Close connection
     void close();
-    
+
     // Terminal size
     Size size();
     void setSizeHandler(Consumer<Size> handler);
-    
+
     // Signal handling
     void setSignalHandler(Consumer<Signal> handler);
-    
+
     // Input handling
     void setStdinHandler(Consumer<int[]> handler);
-    
+
     // Connection state
-    boolean isOpen();
-    
+    boolean reading();  // true when actively reading input
+
     // Session information (SSH)
     Session getSession();
 }
 ```
 
+### Connection Reading State
+
+The `reading()` method indicates whether the connection is actively reading input:
+
+```java
+private void handleConnection(Connection connection) {
+    // For remote connections, reading() is true once accepted
+    if (connection.reading()) {
+        // Handler-based queries work (setStdinHandler)
+        connection.setStdinHandler(input -> {
+            // Process input...
+        });
+    }
+
+    // Continue with readline...
+}
+```
+
+For remote connections:
+- **SSH**: `reading()` returns `true` after the connection handler is invoked
+- **Telnet**: `reading()` returns `true` after binary mode negotiation completes
+- **WebSocket**: `reading()` returns `true` after `openBlocking()` or `openNonBlocking()` is called
+
+When `close()` is called, `reading()` returns `false`.
+```
+
 ### Handling Terminal Resize
 
 ```java

content/docs/readline/getting-started.md

@@ -15,15 +15,15 @@ Add the following dependency to your Maven project:
 <dependency>
   <groupId>org.aesh</groupId>
   <artifactId>readline</artifactId>
-  <version>2.6</version>
+  <version>3.1</version>
 </dependency>
 ```
 
 For Gradle:
 
 ```groovy
 dependencies {
-    implementation 'org.aesh:readline:2.6'
+    implementation 'org.aesh:readline:3.1'
 }
 ```
 

content/docs/readline/installation.md

@@ -13,7 +13,7 @@ Add the dependency to your `pom.xml`:
 <dependency>
   <groupId>org.aesh</groupId>
   <artifactId>readline</artifactId>
-  <version>2.6</version>
+  <version>3.1</version>
 </dependency>
 ```
 
@@ -23,7 +23,7 @@ Add the dependency to your `build.gradle`:
 
 ```groovy
 dependencies {
-    implementation 'org.aesh:readline:2.6'
+    implementation 'org.aesh:readline:3.1'
 }
 ```
 
@@ -47,7 +47,7 @@ mvn clean install
 <dependency>
   <groupId>org.aesh</groupId>
   <artifactId>terminal-ssh</artifactId>
-  <version>2.6</version>
+  <version>3.1</version>
 </dependency>
 ```
 
@@ -57,7 +57,7 @@ mvn clean install
 <dependency>
   <groupId>org.aesh</groupId>
   <artifactId>terminal-telnet</artifactId>
-  <version>2.6</version>
+  <version>3.1</version>
 </dependency>
 ```
 
@@ -67,7 +67,7 @@ mvn clean install
 <dependency>
   <groupId>org.aesh</groupId>
   <artifactId>terminal-http</artifactId>
-  <version>2.6</version>
+  <version>3.1</version>
 </dependency>
 ```