working defaults

README.md

@@ -5,11 +5,14 @@
 ## Features
 
 - **Standard OpenAI interface**: Serves `/v1/chat/completions` and `/v1/models` (with `/chat/completions` and `/models` aliases).
-- **Dual-engine architecture**:
-  - **Browser bridge (`-auto-capture`)**: Routes upstream requests directly through a private, stealth headless Chromium session over CDP. This ensures a 100% genuine Chrome TLS handshake (JA3/JA4), completely bypassing Vercel Security Checkpoints and WAF blocks.
-  - **Direct HTTP client**: Fallback mode for high-throughput environments where valid Vercel clearance cookies and tokens are supplied directly.
+- **Dual-engine architecture (Browser Bridge enabled by default)**:
+  - **Browser bridge (`-auto-capture`, default: true)**: Routes upstream requests directly through a private, stealth offscreen Chromium session over CDP with automatic virtual X server (`Xvfb`) isolation. This ensures a 100% genuine Chrome TLS handshake (JA3/JA4), completely bypassing Vercel Security Checkpoints and WAF blocks out of the box.
+  - **Direct HTTP client (`-direct` / `-no-bridge`)**: Fallback mode for high-throughput environments where valid Vercel clearance cookies and tokens are supplied directly.
+- **Real-time per-token streaming**: Streams tokens in real time over CDP via `Runtime.addBinding` and `ReadableStreamDefaultReader`, passing token chunks immediately through stateful thinking and tool call filters without buffering.
+- **Automated hardware fingerprint rotation & 429 auto-recovery**: Dynamically discovers FingerprintJS entropy modules (or generates high-entropy synthetic fallbacks) and auto-rotates visitor identities upon encountering `HTTP 429` / rate limits, retrying immediately (up to 4 attempts) without dropping client connections.
 - **Private & anti-fingerprinting stealth**:
   - **100% isolated session**: Launches in `--incognito` mode with a temporary ephemeral user profile and `--disable-extensions`, completely segregated from any existing Chromium/Chrome windows, history, extensions, or sessions.
+  - **Auto-managed virtual display (`-xvfb`, default: true)**: Spawns an isolated Xvfb display to completely isolate Chromium from tiling window managers (i3, bspwm, sway, dwm).
   - **Zero port collisions**: Binds to a dynamically allocated ephemeral loopback port for CDP commands.
   - **Stealth & anti-detection**:
     - Disables Blink automation features (`--disable-blink-features=AutomationControlled`).
@@ -19,7 +22,6 @@
     - Strips telemetry, domain reliability, crash reporting, and sync.
 - **Dynamic token ingestion API**: Provides `GET /v1/token` and `POST /v1/token` to inspect or hot-reload single-use hCaptcha tokens and cookies on the fly without restarting the server.
 - **Fast fail & clear error propagation**: Non-transient errors (such as `captcha_failed` or `invalid_params`) return immediately (<300ms) without wasting time in exponential backoff retry loops.
-- **Streaming & non-streaming**: Full support for Server-Sent Events (`stream: true`) and standard JSON responses (`stream: false`).
 - **Reasoning content separation**: Parses `<think>...</think>` tags and upstream reasoning chunks into `reasoning_content` deltas / message fields.
 - **Function / tool calling translation**: Injects tool schemas into system instructions, maps multi-turn tool calling history, and parses model tool invocations into standard OpenAI `tool_calls`.
 - **Zero external dependencies**: Implemented using pure Go standard library.
@@ -41,19 +43,24 @@ Binary will be produced at `bin/th3ist`.
 ## Running
 
 ```bash
-# Run with Browser Bridge active (recommended for bypassing Vercel TLS checkpoint)
-./bin/th3ist -auto-capture
+# Run with default settings (Browser Bridge and isolated Xvfb active)
+./bin/th3ist
 
 # Run on a custom port with static defaults
 ./bin/th3ist -port 9000 -default-model gemini-3.5-flash-lite
+
+# Run in direct HTTP client mode (bypasses browser bridge)
+./bin/th3ist -direct
 ```
 
 ### CLI flags
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `-auto-capture` | Enable private browser bridge (bypasses Vercel TLS & mints fresh tokens) | `false` |
-| `-xvfb` | Automatically spawn and manage an isolated virtual X server (`Xvfb`) for complete isolation from tiling window managers | `false` |
+| `-auto-capture` | Enable private browser bridge (bypasses Vercel TLS & mints fresh tokens) | `true` |
+| `-direct` / `-no-bridge` | Disable browser bridge and run in direct HTTP mode | `false` |
+| `-xvfb` / `-Xvfb` | Automatically spawn and manage an isolated virtual X server (`Xvfb`) for complete isolation from tiling window managers | `true` |
+| `-no-xvfb` | Disable automatic virtual X server (uses active `$DISPLAY`) | `false` |
 | `-display` | Custom X11 DISPLAY to attach Chromium to (e.g. `:99` for an existing Xvfb / Xephyr / Xnest session) | *(auto / `$DISPLAY`)* |
 | `-headless` | Force strict headless mode `--headless=new` (defaults to offscreen window when display is present) | `false` |
 | `-browser-bin` | Custom path to Chromium/Google Chrome binary | *(auto-detected)* |
@@ -68,20 +75,14 @@ Binary will be produced at `bin/th3ist`.
 
 ### Tiled window managers & virtual display isolation
 
-On tiling window managers (e.g., i3, bspwm, sway, dwm, awesome, hyprland, xmonad), any window created on the main `$DISPLAY` may be caught and tiled into the current workspace.
+On tiling window managers (e.g., i3, bspwm, sway, dwm, awesome, hyprland, xmonad), `th3ist` defaults to managing an isolated virtual X server (`-xvfb`) so that no Chromium windows appear on your desktop workspace:
 
-To prevent any windows from appearing on your desktop:
-
-1. **Option A: Auto-managed Xvfb (`-xvfb`)**:
+1. **Option A: Auto-managed Xvfb (Default)**:
    Install `xorg-server-xvfb` (or `Xfbdev`):
    - **Void Linux**: `sudo xbps-install -S xorg-server-xvfb`
    - **Debian / Ubuntu**: `sudo apt install xvfb`
    - **Arch Linux**: `sudo pacman -S xorg-server-xvfb`
 
-   Then run `th3ist` with `-xvfb`:
-   ```bash
-   ./bin/th3ist -auto-capture -xvfb -port 9000
-   ```
    `th3ist` will automatically allocate an isolated virtual display (e.g. `:99`), launch `Xvfb`, attach Chromium to it, and cleanly terminate `Xvfb` on exit.
 
 2. **Option B: Manual virtual X server (`Xvfb`, `Xephyr`, or `Xnest`)**:
@@ -90,7 +91,7 @@ To prevent any windows from appearing on your desktop:
    Xvfb :99 -screen 0 1280x800x24 -ac &
 
    # Run th3ist attached to display :99
-   ./bin/th3ist -auto-capture -display :99 -port 9000
+   ./bin/th3ist -display :99 -port 9000
    ```
 
 3. **Option C: Tiling window manager rules (`--class=th3ist_hidden`)**: