feat: add WSL wrapper runner and performance docs

README.md

@@ -1,15 +1,17 @@
-# Codex DMG -> Windows
+# Codex DMG Wrapper (Windows / WSL)
 
-This repository provides a **Windows-only runner** that extracts the macOS Codex DMG and runs the Electron app on Windows. It unpacks `app.asar`, swaps mac-only native modules for Windows builds, and launches the app with a compatible Electron runtime. It **does not** ship OpenAI binaries or assets; you must supply your own DMG and install the Codex CLI.
+This repository is a wrapper around the official macOS Codex app package (`Codex.dmg`): it extracts `app.asar`, patches platform-specific native modules, and launches with a compatible Electron runtime on Windows or WSL/Linux.
 
-## Requirements
+It is **not** an OpenAI binary distribution and it does **not** auto-download Codex for you. You must download `Codex.dmg` yourself and provide it locally.
+
+## Requirements (Windows runner)
 - Windows 10/11
 - Node.js
 - 7-Zip (`7z` in PATH)
 - If 7-Zip is not installed, the runner will try `winget` or download a portable copy
 - Codex CLI installed (`npm i -g @openai/codex`)
 
-## Quick Start
+## Quick Start (Windows)
 1. Place your DMG in the repo root (default name `Codex.dmg`).
 2. Run:
 
@@ -35,10 +37,95 @@ The script will:
 - Auto-detect `codex.exe`
 - Launch Codex
 
+## Quick Start (WSL/Linux)
+1. Download `Codex.dmg` from the official source, then copy or reference it (example from Windows Downloads):
+
+```bash
+cp "/mnt/c/Users/<you>/Downloads/Codex.dmg" ./Codex.dmg
+```
+
+2. Ensure Node.js + Codex CLI are installed:
+
+```bash
+npm i -g @openai/codex
+```
+
+3. Run the WSL/Linux runner:
+
+```bash
+chmod +x ./scripts/run.sh
+./scripts/run.sh --dmg ./Codex.dmg
+```
+
+Recommended default on WSL (best visual quality in most setups):
+
+```bash
+CODEX_OZONE_PLATFORM=wayland ./scripts/run.sh --dmg ./Codex.dmg --reuse
+```
+
+Useful options:
+
+```bash
+./scripts/run.sh --dmg ./Codex.dmg --no-launch
+./scripts/run.sh --dmg ./Codex.dmg --reuse
+./scripts/run.sh --dmg ./Codex.dmg --codex-cli "$(command -v codex)"
+```
+
+Notes for WSL/Linux:
+- `scripts/run.sh` needs `7z`. If not present, it tries to bootstrap a local `7zip` binary under `work/tools/` using `apt-get download` (no `sudo` install required).
+- GUI launch requires WSLg/X forwarding (`DISPLAY` or `WAYLAND_DISPLAY`).
+- If the window looks blurry/pixelated on WSL, force Wayland + scale factor:
+
+```bash
+CODEX_OZONE_PLATFORM=wayland CODEX_FORCE_DEVICE_SCALE_FACTOR=1 ./scripts/run.sh --dmg ./Codex.dmg --reuse
+```
+
+- If Fullscreen/Maximize is broken on Wayland, run without forced Wayland decorations (default):
+
+```bash
+CODEX_OZONE_PLATFORM=wayland ./scripts/run.sh --dmg ./Codex.dmg --reuse
+```
+
+- If the cursor is too large, set a cursor size explicitly:
+
+```bash
+CODEX_OZONE_PLATFORM=wayland CODEX_CURSOR_SIZE=16 ./scripts/run.sh --dmg ./Codex.dmg --reuse
+```
+
+(`CODEX_CURSOR_SIZE` valid range: `12-128`)
+
+- If the window is invisible/off-screen, force explicit position/size:
+
+```bash
+CODEX_OZONE_PLATFORM=x11 XCURSOR_SIZE=16 CODEX_WINDOW_POSITION=80,80 CODEX_WINDOW_SIZE=1400,900 ./scripts/run.sh --dmg ./Codex.dmg --reuse
+```
+
+- `CODEX_DISABLE_GPU=1` is currently not recommended for this app build on WSL, because it can make the UI non-interactive/invisible.
+
+### WSLg refresh rate tuning (scroll performance)
+
+If scrolling feels like low FPS, set WSLg monitor refresh rate explicitly in Windows.
+
+In **PowerShell (Run as Administrator)**:
+
+```powershell
+$cfg = "C:\ProgramData\Microsoft\WSL\.wslgconfig"
+New-Item -ItemType Directory -Force -Path (Split-Path $cfg) | Out-Null
+Set-Content -Path $cfg -Encoding ascii -Value "[system-distro-env]`nWESTON_RDP_MONITOR_REFRESH_RATE=144"
+wsl --shutdown
+```
+
+Notes:
+- Use `144` for 144Hz displays.
+- Use `120` for 120Hz displays.
+- Use `60` for 60Hz displays.
+- After `wsl --shutdown`, reopen WSL and run Codex again.
+
 ## Notes
 - This is not an official OpenAI project.
 - Do not redistribute OpenAI app binaries or DMG files.
 - The Electron version is read from the app's `package.json` to keep ABI compatibility.
+- Auto-downloading the macOS Codex DMG is intentionally not included.
 
 ## License
 MIT (For the scripts only)