pi-sync-system-theme 0.2.0 → 0.2.2

package/README.md

@@ -33,6 +33,17 @@ pi install npm:pi-sync-system-theme
 > pi remove npm:pi-system-theme
 > ```
 
+## Package rename migration
+
+This package was renamed from `pi-system-theme-ssh-bridge` to `pi-sync-system-theme`.
+
+If you installed the old package name, run:
+
+```bash
+pi remove npm:pi-system-theme-ssh-bridge
+pi install npm:pi-sync-system-theme
+```
+
 ## Configuration
 
 Use the `/system-theme` command inside pi to configure:
@@ -67,6 +78,30 @@ For environments where neither OSC 11 nor OS detection works, you can push an ov
 }
 ```
 
+## ⚠️ Performance tuning notes (important)
+
+This extension queries terminal background color (OSC 11) in SSH/tmux sessions. Aggressive polling can cause terminal artifacts (garbled startup output) or input lag on some terminal/SSH combinations.
+
+Recommended ranges:
+
+- `pollMs`: **3000–8000** (default `8000`)
+- `PI_SYSTEM_THEME_OSC11_MIN_INTERVAL_MS`: **8000–15000** (default `15000`)
+
+Avoid overly aggressive values unless you have tested your environment thoroughly:
+
+- `pollMs < 2000`
+- `PI_SYSTEM_THEME_OSC11_MIN_INTERVAL_MS < 5000`
+
+If you notice lag, slash-command stutter, or startup artifacts:
+
+1. Increase `pollMs`
+2. Increase `PI_SYSTEM_THEME_OSC11_MIN_INTERVAL_MS`
+3. Temporarily disable OSC11 probing with:
+
+```bash
+export PI_SYSTEM_THEME_OSC11_ENABLED=0
+```
+
 ## Environment variables
 
 | Variable | Default | Description |
@@ -74,13 +109,14 @@ For environments where neither OSC 11 nor OS detection works, you can push an ov
 | `PI_SYSTEM_THEME_OVERRIDE_FILE` | `~/.pi/agent/system-theme-override.json` | Override file path |
 | `PI_SYSTEM_THEME_OVERRIDE_MAX_AGE_MS` | `60000` | Max age before override is considered stale |
 | `PI_SYSTEM_THEME_OSC11_ENABLED` | `1` | Enable/disable OSC 11 terminal query (`0` to disable) |
-| `PI_SYSTEM_THEME_OSC11_MIN_INTERVAL_MS` | `15000` | Minimum interval between OSC 11 probes in SSH sessions |
+| `PI_SYSTEM_THEME_OSC11_MIN_INTERVAL_MS` | `15000` | Minimum interval between OSC 11 probes in SSH/tmux sessions |
 
 ## Compatibility
 
 - **Terminals:** Any terminal supporting OSC 11 color queries (Ghostty, iTerm2, kitty, foot, WezTerm, xterm, etc.)
 - **OS detection:** macOS, Linux (GNOME gsettings), Windows
 - **SSH:** Works transparently — no special setup required
+- **tmux:** Supported (including long-lived sessions where `SSH_*` env vars may be missing)
 - **Ghostty `theme = auto`:** Fully supported. When Ghostty switches colors, the next poll detects it.
 
 ## Migrating from pi-system-theme

package/index.ts

@@ -116,6 +116,10 @@ function isSSHSession(): boolean {
     return !!(process.env.SSH_CONNECTION || process.env.SSH_TTY || process.env.SSH_CLIENT);
 }
 
+function isTmuxSession(): boolean {
+    return typeof process.env.TMUX === "string" && process.env.TMUX.length > 0;
+}
+
 // ---------------------------------------------------------------------------
 // Config I/O  (reads ~/.pi/agent/system-theme.json written by /system-theme)
 // ---------------------------------------------------------------------------
@@ -212,8 +216,9 @@ let fd;
 try { fd = fs.openSync('/dev/tty', fs.constants.O_RDWR | fs.constants.O_NOCTTY | O_NONBLOCK); }
 catch { process.exit(1); }
 
-// Send OSC 11 query (BEL terminator is widely supported)
-try { fs.writeSync(fd, '\x1b]11;?\x07'); }
+// Send OSC 11 query.
+// Use ST terminator for better compatibility with tmux passthrough.
+try { fs.writeSync(fd, '\x1b]11;?\x1b\\'); }
 catch { try { fs.closeSync(fd); } catch {} process.exit(1); }
 
 const buf = Buffer.alloc(1024);
@@ -235,13 +240,21 @@ function tryRead() {
     }
 }
 
+function to8Bit(hex) {
+    if (!hex) return 0;
+    const h = String(hex);
+    if (h.length <= 2) return parseInt(h.padEnd(2, h[h.length - 1] || '0'), 16);
+    return parseInt(h.slice(0, 2), 16);
+}
+
 function done() {
     try { fs.closeSync(fd); } catch {}
-    const m = response.match(/\x1b\]11;rgb:([0-9a-fA-F]+)\\/([0-9a-fA-F]+)\\/([0-9a-fA-F]+)(?:\x07|\x1b\\\\)/);
+    // Keep parser permissive: tmux may wrap control sequences, but rgb payload remains stable.
+    const m = response.match(/rgb:([0-9a-fA-F]{2,4})\\/([0-9a-fA-F]{2,4})\\/([0-9a-fA-F]{2,4})/);
     if (m) {
-        const r = parseInt(m[1].slice(0, 2), 16);
-        const g = parseInt(m[2].slice(0, 2), 16);
-        const b = parseInt(m[3].slice(0, 2), 16);
+        const r = to8Bit(m[1]);
+        const g = to8Bit(m[2]);
+        const b = to8Bit(m[3]);
         const luminance = 0.299 * r + 0.587 * g + 0.114 * b;
         process.stdout.write(luminance < 128 ? 'dark' : 'light');
     }
@@ -250,7 +263,7 @@ function done() {
 
 function poll() {
     tryRead();
-    if (response.includes('\x1b]11;') || Date.now() > deadline) return done();
+    if (response.includes('rgb:') || Date.now() > deadline) return done();
     setTimeout(poll, 16);
 }
 
@@ -406,8 +419,9 @@ async function resolveAppearance(config: Config, osc11State: Osc11State): Promis
     if (override === "dark" || override === "light") return override;
     // "auto" or null → continue
 
-    // 2. Terminal query via OSC 11 (SSH only, throttled)
-    if (isSSHSession() && isOsc11Enabled()) {
+    // 2. Terminal query via OSC 11 (SSH/tmux, throttled)
+    // tmux sessions may not carry SSH_* vars, so include TMUX explicitly.
+    if ((isSSHSession() || isTmuxSession()) && isOsc11Enabled()) {
         const now = Date.now();
         const minIntervalMs = getOsc11MinIntervalMs();
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pi-sync-system-theme",
-    "version": "0.2.0",
+    "version": "0.2.2",
     "description": "Sync pi theme with system appearance — works locally and over SSH via OSC 11 terminal queries",
     "keywords": [
         "pi-package",